hakari

hakari

Semi-autonomous paper trading pipeline built as a Claude Code plugin. 6-stage analysis with 5 validation hooks, deterministic safety gates, and mandatory human approval before every trade.

What it does

Screens markets, runs multi-timeframe technical analysis, checks SEC fundamentals, sizes positions using Minervini risk rules, runs an adversarial challenge against every trade thesis, then presents a proposal card for human approval. Executes on Alpaca paper trading only.

Pipeline

Discovery (screener + sector rotation + watchlist)
  -> Stage 0: Morning scan (sentiment, news)
  -> Stage 1: Market context (SPY/VIX, regime detection)
  -> Hook 1: Context validator (exposure ceiling)        [validate.mjs]
  -> Stage 2: Signal generation (TA, Darwinian-weighted)
  -> Hook 2: Signal coherence (2+ confirming sources)    [LLM]
  -> Stage 3: Fundamental check (SEC filings)
  -> Hook 3: Fundamental sanity                          [LLM]
  -> Stage 4: Position sizing (Minervini formula)        [validate.mjs]
  -> Hook 4: Risk guardrails (1% risk, circuit breaker)  [validate.mjs]
  -> Stage 4b: Adversarial challenge (devil's advocate)
  -> Hook 5: Adversarial gate                            [LLM]
  -> Stage 5: Proposal card -> Human approval -> Preflight [validate.mjs] -> Execute

Risk model

Rule	Limit
Max risk per trade	1% of account equity
Daily circuit breaker	5% loss halts trading
Max stop distance	8% (Minervini cap)
Min R:R	1.5:1 (hard), 2:1 (preferred)
Max open positions	5
Position entry	50% initial, add at +1R
Exposure ratchet	Tighten-only (never loosens intra-session)

Prerequisites

• Claude Code CLI or desktop app
• sops (brew install sops)
• age (brew install age)
• uv (brew install uv) — for MCP servers via uvx
• Node.js 22+ — for validate.mjs

Setup

1. Clone and run setup

git clone https://github.com/JediNight/hakari.git
cd hakari
./setup.sh

The setup script will:

• Check prerequisites
• Generate an age key pair (if you don't have one)
• Attempt to decrypt secrets.enc.yaml with your age key
• Print your public key if you need to be added as an authorized recipient

2. Configure your API keys

If you're the repo owner (your age key is already in .sops.yaml):

# Keys are already encrypted — setup.sh handles decryption
./setup.sh

If you're a collaborator:

Option A — Get added to the encryption recipients:

# Send your age public key to the repo owner
grep "public key:" ~/.config/sops/age/keys.txt

# Owner adds your key to .sops.yaml, re-encrypts, and pushes

Option B — Use your own keys:

cp secrets.example.yaml secrets.yaml
# Edit secrets.yaml with your Alpaca paper trading keys
# (Create a free paper account at https://app.alpaca.markets/signup)

# Update .sops.yaml with your age public key, then encrypt
sops -e secrets.yaml > secrets.enc.yaml
rm secrets.yaml

3. Install the plugin

claude plugin add /path/to/hakari
# or
claude plugin add github:JediNight/hakari

4. Run it

In Claude Code, invoke the skill:

/trading-orchestrator

Or just ask Claude to run the pipeline:

Run the morning scan and build today's watchlist

MCP servers

Server	Purpose	Install	Keys needed
alpaca	Paper trading execution, quotes, account	uvx alpaca-mcp-server	ALPACA_API_KEY, ALPACA_SECRET_KEY
tradingview	TA, screening, sentiment, backtesting	uvx tradingview-mcp	None
edgartools	SEC filings, fundamentals, insider txns	uvx --from "edgartools[ai]" edgartools-mcp	EDGAR_IDENTITY (email)

The .mcp.json in this repo configures all three servers. Keys are read from environment variables, which setup.sh populates from the encrypted secrets.enc.yaml.

Key management

Secrets are encrypted with SOPS using age keys. No plaintext credentials are ever committed.

secrets.example.yaml   # Template — safe to commit
secrets.enc.yaml       # Encrypted — safe to commit
secrets.yaml           # Decrypted — NEVER commit (in .gitignore)

Adding a collaborator

# Get their age public key
# Add it to .sops.yaml creation_rules[0].age (comma-separated)
# Re-encrypt:
sops updatekeys secrets.enc.yaml
git add .sops.yaml secrets.enc.yaml && git commit -m "chore: add collaborator key"

Project structure