Finyx

An AI-powered personal finance advisor for Claude Code. Tax optimization, investment portfolio analysis, pension planning, insurance, real estate, and a unified financial insights dashboard — delivered as model-invoked skills that you talk to in plain language.

"Set up my financial profile"              → finyx-profile
"How can I optimize my taxes?"             → finyx-tax
"Review my ETF portfolio"                  → finyx-invest
"Am I saving enough for retirement?"       → finyx-pension
"Check my insurance coverage"              → finyx-insurance
"Analyze this property in Kassel"          → finyx-realestate
"How am I doing financially?"              → finyx-insights
"Help me prepare for my doctor visit"      → finyx-health
"Check my medications for interactions"    → finyx-health meds
"I need a second opinion on surgery"       → finyx-health second-opinion

There are no slash commands to memorize. Claude routes to the right skill based on what you ask.

What it does

Finyx is a Claude Code plugin made up of seven specialist skills sharing a single financial profile. Each skill knows its domain (tax, investing, pension, insurance, real estate) and reads .finyx/profile.json for context. They give integrated, country-aware advice — not siloed single-domain recommendations.

Key capabilities:

• Tax advisor — German (Abgeltungssteuer, Sparerpauschbetrag, Vorabpauschale, Teilfreistellung) and Brazilian (IR, DARF, come-cotas, FII exemptions) investment tax guidance, plus DBA cross-border mechanics for expats
• Investment advisor — Portfolio analysis, risk profiling, ETF recommendations, rebalancing, broker comparison (DE + BR with live discovery), with live market data (Finnhub, brapi.dev)
• Pension planning — Riester/Rürup/bAV (DE), PGBL/VGBL/INSS (BR), cross-country retirement projection
• Insurance advisor — 13 German insurance product types (Haftpflicht, Hausrat, Kfz, Rechtsschutz, GKV/PKV health, and more), portfolio gap detection, PDF policy parsing
• Real estate analysis — Seven-workflow pipeline: scout, analyze (Sonder-AfA §7b, Kaufnebenkosten), filter, compare, stress-test, advisor briefing in DE/EN/PT, mortgage rates
• Financial insights — Cross-domain health dashboard with income allocation, tax efficiency score, net worth snapshot, goal pace tracking, and ranked top-5 actions by € impact
• Health advisor (MDR-safe) — Pre-visit preparation for adults in Germany: symptom intake (OPQRST/SOCRATES), medical record decoding (Arztbriefe, Laborbefunde), PRISCUS 2.0 medication check for adults ≥65, §27b SGB V second-opinion case structuring, doctor sourcing (KV Berlin, certified Zentren), G-BA Vorsorgekatalog gap analysis, and longitudinal health diary with optional Home Assistant sensor overlay
• Cross-border support — Built for expats with obligations in multiple jurisdictions (Germany + Brazil)

Installation

Option A: Claude Code plugin (recommended)

claude plugin add github:italolelis/finyx

Requires Claude Code.

Option B: npm (provides the finyx CLI for status/help)

npm install -g @italolelis/finyx

This installs the finyx CLI for project status, help text, and version checks. It does not install the skills themselves — use Option A for that.

Quick start

1. Set up your profile (mandatory first step):

   "Set up my financial profile"

   Claude invokes finyx-profile, runs a 5-minute interview (residency, tax data, family, goals, risk tolerance), and creates .finyx/profile.json.

2. Ask for advice in plain language:

   • "How can I improve my tax situation?" → finyx-tax
   • "Review my portfolio and suggest rebalancing" → finyx-invest
   • "What's my retirement gap?" → finyx-pension
   • "Do I have insurance gaps?" → finyx-insurance
   • "Analyze this Kassel property" → finyx-realestate
   • "Give me a financial health check" → finyx-insights

3. CLI utilities (if installed via npm):

   finyx help      # Capability summary
   finyx status    # Profile + project state
   finyx version

Configuration

By default, Finyx reads your financial profile from ./.finyx/profile.json (project-local) or ~/.finyx/profile.json (global fallback). You can override this via an environment variable or a user-level config file.

Profile path precedence

| # | Source | Notes | |---|--------|-------| | 1 | $FINYX_PROFILE env var | Highest priority. Must point to an existing file. | | 2 | ~/.config/finyx/config.json profile_path key | User-level default. | | 3 | ./.finyx/profile.json | Project-local profile in current working directory. | | 4 | ~/.finyx/profile.json | Global fallback. Used when none of the above exist. |

If $FINYX_PROFILE or config.json's profile_path is set but the file does not exist, Finyx fails loudly with a clear error rather than silently falling through. This prevents silent desync.

Examples

# Per-shell override
export FINYX_PROFILE="$HOME/Documents/finances/personal-profile.json"

# User-level default
mkdir -p ~/.config/finyx
cat > ~/.config/finyx/config.json <<'JSON'
{ "profile_path": "/Users/me/Documents/finances/personal-profile.json" }
JSON

Working artifacts stay project-local

Only profile.json is relocatable. Per-project working artifacts always live under ./.finyx/ of the current working directory regardless of where profile.json is stored:

| Path | Purpose | |------|---------| | ./.finyx/insights-config.json | Allocation mapping persisted by finyx-insights | | ./.finyx/research/ | Location and market research output | | ./.finyx/analysis/ | Per-location analysis (UNITS, RANKED, SHORTLIST) | | ./.finyx/output/ | Generated briefings | | ./.finyx/STATE.md | Per-project workflow state |

For implementation details, see scripts/README.md.

Skills

| Skill | Purpose | |-------|---------| | finyx-profile | Financial profile interview — the mandatory first step | | finyx-tax | Investment tax advisor (DE + BR + cross-border DBA) | | finyx-invest | Portfolio analysis, ETFs, rebalancing, broker comparison | | finyx-pension | Riester/Rürup/bAV (DE), PGBL/VGBL/INSS (BR) | | finyx-insurance | 13 German insurance types via sub-skill dispatch | | finyx-realestate | Scout → analyze → filter → compare → stress-test → report | | finyx-insights | Cross-domain financial health dashboard | | finyx-health | Pre-visit preparation — symptom intake, record decoding, medication checks (PRISCUS 2.0), §27b second opinions, doctor sourcing, prevention gap analysis | | finyx-home | Home environment health monitoring via Home Assistant — sensor data overlay for health diary |

Each skill is self-contained with its own SKILL.md, LICENSE.txt, and references/ directory. See skills/README.md for the skill-author convention.

How it works

Finyx is a Claude Code plugin built on Anthropic's Agent Skills format. No application framework — every skill is SKILL.md plus reference markdown, loaded on demand via progressive disclosure.

finyx/
├── .claude-plugin/
│   ├── plugin.json                  # Plugin manifest
│   └── marketplace.json             # Marketplace listing
├── bin/finyx.js                     # Optional CLI (help/status/version)
├── scripts/resolve-profile.sh       # Shared 4-tier profile path resolver
├── skills/
│   ├── README.md                    # Skill-author conventions
│   ├── profile/                     # finyx-profile
│   ├── tax/                         # finyx-tax
│   ├── invest/                      # finyx-invest
│   ├── pension/                     # finyx-pension
│   ├── insurance/                   # finyx-insurance (with sub-skills/)
│   ├── realestate/                  # finyx-realestate (with workflows/, agents/)
│   └── insights/                    # finyx-insights
└── LICENSE                          # MIT

Zero runtime dependencies. Everything is Markdown consumed by Claude Code via the plugin system. The finyx Node CLI is a small convenience utility — Finyx works fully without it.

Country support

| Country | Tax | Investment | Pension | Real Estate | Insurance | |---------|-----|-----------|---------|-------------|-----------| | Germany | Abgeltungssteuer, Sparerpauschbetrag, Vorabpauschale, Teilfreistellung | ETF/stock analysis, live Finnhub data, brokers | Riester, Rürup, bAV | Full pipeline (Erbpacht, AfA §7b, etc.) | 13 product types incl. GKV/PKV | | Brazil | IR, DARF, come-cotas, FII exemptions | B3 analysis, live brapi.dev data, brokers | PGBL, VGBL, INSS | Out of scope in v1 | Out of scope in v1 |

Cross-border users get integrated advice across both jurisdictions with DBA residency tiebreaker and withholding credit mechanics.

Legal disclaimer

Finyx provides financial information for educational and planning purposes only. This tool does not constitute financial, tax, legal, or investment advice. Always consult qualified professionals (Steuerberater, Versicherungsmakler, financial advisor) before making financial decisions.

License

MIT — See LICENSE for details.

Finyx: Your AI financial advisor that sees the full picture.

Built with Claude Code.