https://github.com/2165187809-axe/clawdfolio
AI portfolio monitoring for Clawdbot with v2 finance workflows, option analytics, and a battle-tested options strategy playbook
https://github.com/2165187809-axe/clawdfolio
claude-code finance investment longport moomoo portfolio portfolio-management python quantitative-finance risk-analysis stocks trading
Last synced: 4 months ago
JSON representation
AI portfolio monitoring for Clawdbot with v2 finance workflows, option analytics, and a battle-tested options strategy playbook
- Host: GitHub
- URL: https://github.com/2165187809-axe/clawdfolio
- Owner: 2165187809-AXE
- License: mit
- Created: 2026-02-06T05:31:56.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-10T03:43:24.000Z (4 months ago)
- Last Synced: 2026-02-10T07:56:18.085Z (4 months ago)
- Topics: claude-code, finance, investment, longport, moomoo, portfolio, portfolio-management, python, quantitative-finance, risk-analysis, stocks, trading
- Language: Python
- Size: 259 KB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Clawdfolio π¦π
[](https://github.com/2165187809-AXE/clawdfolio/actions/workflows/ci.yml)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/2165187809-AXE/clawdfolio)
[](https://github.com/anthropics/claude-code)
English | [δΈζ](README_CN.md)
> **AI-powered portfolio monitoring for the Clawdbot ecosystem.**
>
> A production-oriented Clawdbot finance skill - aggregates portfolios from multiple brokers, calculates institutional-grade risk metrics, and generates intelligent trading alerts with production-grade data reliability. Its options methodology is synthesized from authoritative books and courses, validated through rigorous backtesting, and refined in multi-year live trading.
---
## Why Clawdfolio?
| Traditional Tools | Clawdfolio |
|-------------------|------------|
| Manual data entry | Auto-sync from brokers |
| Basic P&L tracking | VaR, Sharpe, Beta, Max Drawdown |
| Single broker view | Multi-broker aggregation |
| Spreadsheet alerts | Smart RSI/price alerts |
| No AI integration | **Clawdbot native skill** |
---
## Features
- **Multi-Broker Support** - Longport (Longbridge), Moomoo/Futu, or demo mode
- **Risk Analytics** - Volatility, Beta, Sharpe Ratio, Value at Risk, Max Drawdown
- **Technical Analysis** - RSI, SMA, EMA, Bollinger Bands
- **Concentration Analysis** - HHI index, sector exposure, correlation warnings
- **Smart Alerts** - Price movements, RSI extremes, P&L thresholds
- **Earnings Calendar** - Track upcoming earnings for holdings
- **DCA Analysis** - Dollar-cost averaging signals
- **Options Toolkit** - Option quote/Greeks, option chain snapshot, buyback trigger monitor
- **Options Strategy Playbook (v2.1)** - Dedicated methodology for Covered Call and Sell Put lifecycle management, with delta/gamma/margin guardrails
- **Finance Workflow Suite (v2)** - 20 migrated production workflows from local `~/clawd/scripts`, categorized and runnable via `clawdfolio finance`
---
## What's New in v2.1.0
- **Dedicated options strategy documentation** - Added `docs/OPTIONS_STRATEGY_PLAYBOOK_v2.1.md` as the canonical playbook for CC and Sell Put
- **Research-to-execution alignment** - Formalized a framework synthesized from authoritative options books and courses, data-driven backtesting, and multi-year live trading
- **Risk-first policy upgrade** - Added explicit gamma-risk, margin, leverage, roll, assignment, and pause-condition decision rules
- **Feature mapping clarity** - Connected strategy decisions to `clawdfolio options` and `clawdfolio finance` workflows
Read the full playbook: `docs/OPTIONS_STRATEGY_PLAYBOOK_v2.1.md`
---
## What's New in v2.0.0
- **Full finance migration** - Migrated all active local finance workflows (reports, briefs, alerts, market intel, snapshots, DCA, security) from `~/clawd/scripts`
- **Structured orchestration** - Added `clawdfolio finance` command group to list, initialize, and run workflows by id
- **Organized layout** - Added categorized workflow catalog and bundled `legacy_finance` package content, with archived historical scripts retained
- **Runtime safety** - Introduced mutable workspace bootstrap (`~/.clawdfolio/finance`) so legacy workflows keep writable config/state without polluting repo root
- **Prior reliability gains retained** - Wilder RSI smoothing, Longport symbol fix, yfinance hardening, options quote/chain/buyback monitor remain included
---
## Quick Start
### As Clawdbot Skill
Run in Clawdbot:
```
/clawdfolio summary
/clawdfolio risk
/clawdfolio quotes AAPL MSFT NVDA
/clawdfolio alerts
```
`clawdfolio` is also CLI-compatible with Claude Code environments.
### CLI Installation
```bash
# Basic
pip install clawdfolio
# With broker support
pip install clawdfolio[longport] # Longport
pip install clawdfolio[futu] # Moomoo/Futu
pip install clawdfolio[all] # All brokers
```
### CLI Usage
```bash
clawdfolio summary # Portfolio overview
clawdfolio risk # Risk metrics
clawdfolio quotes AAPL TSLA # Real-time quotes
clawdfolio alerts # Check alerts
clawdfolio earnings # Upcoming earnings
clawdfolio dca AAPL # DCA analysis
clawdfolio options expiries TQQQ
clawdfolio options quote TQQQ --expiry 2026-06-18 --strike 60 --type C
clawdfolio options chain TQQQ --expiry 2026-06-18 --side both --limit 10
clawdfolio options buyback # Trigger check from config option_buyback.targets
clawdfolio finance list # List all migrated finance workflows
clawdfolio finance init # Bootstrap ~/.clawdfolio/finance workspace
clawdfolio finance run portfolio_daily_brief_tg_clean
```
### Finance Workflows (v2)
`clawdfolio finance list` groups workflows by:
- Portfolio Reports
- Briefing Cards
- Alerts and Monitors
- Market Intelligence
- Broker Snapshots
- Strategy
- Security
---
## Python API
```python
from clawdfolio.brokers import get_broker
from clawdfolio.analysis import analyze_risk
# Connect to broker
broker = get_broker("demo") # or "longport", "futu"
broker.connect()
# Get portfolio and analyze
portfolio = broker.get_portfolio()
metrics = analyze_risk(portfolio)
print(f"Net Assets: ${portfolio.net_assets:,.2f}")
print(f"Sharpe Ratio: {metrics.sharpe_ratio:.2f}")
print(f"VaR 95%: ${metrics.var_95:,.2f}")
```
---
## Risk Metrics
| Metric | Description |
|--------|-------------|
| **Volatility** | 20-day and 60-day annualized |
| **Beta** | Correlation with SPY/QQQ |
| **Sharpe Ratio** | Risk-adjusted returns |
| **VaR** | Value at Risk (95%/99%) |
| **Max Drawdown** | Largest peak-to-trough decline |
| **HHI** | Portfolio concentration index |
---
## Configuration
### Environment Variables
```bash
# Longport
export LONGPORT_APP_KEY=your_app_key
export LONGPORT_APP_SECRET=your_app_secret
export LONGPORT_ACCESS_TOKEN=your_access_token
# Moomoo: Run OpenD locally on port 11111
```
### Config File (optional)
Create `config.yaml`:
```yaml
brokers:
longport:
enabled: true
futu:
enabled: true
extra:
host: "127.0.0.1"
port: 11111
alerts:
pnl_trigger: 500.0
rsi_high: 80
rsi_low: 20
option_buyback:
enabled: true
symbol: "TQQQ"
state_path: "~/.cache/clawdfolio/option_buyback_state.json"
targets:
- name: "target1"
strike: 60
expiry: "2026-06-18"
type: "C"
trigger_price: 1.60
qty: 2
reset_pct: 0.20
- name: "target2"
strike: 60
expiry: "2026-06-18"
type: "C"
trigger_price: 0.80
qty: 1
reset_pct: 0.20
```
---
## Supported Brokers
| Broker | Region | Status |
|--------|--------|--------|
| Demo | Global | Built-in |
| Longport | US/HK/SG | Optional |
| Moomoo/Futu | US/HK/SG | Optional |
---
## Contributing
Contributions welcome! Please submit a Pull Request.
---
## License
MIT License - see [LICENSE](LICENSE)
---
## Links
- [GitHub Repository](https://github.com/2165187809-AXE/clawdfolio)
- [Report Issues](https://github.com/2165187809-AXE/clawdfolio/issues)
- [Claude Code Compatibility](https://github.com/anthropics/claude-code)
---
**If Clawdfolio helps you, please give it a β star!**