cupel

cupel · v0.1 · MIT

A personal investing analyst

cupel turns the LLM in your AI harness into a research companion that learns your edges and tests your ideas against the investing canon. It lives in one folder and keeps a dated record of your thinking. It gives reasoned, mandate-grounded calls — the likely scenarios, rough upside and timeframe, and the risks named. It refuses false precision dressed as fact and bare tips with no reasoning, and never places trades; the decisions stay yours.

001Start

Use what you already know

The premise is Peter Lynch’s: your edge is what you already know from your work and daily life — the products you watch take off, the industry shifts you see before the analysts do. A familiar name is only a lead, though; it still has to survive the homework.

cupel turns the LLM in your AI harness into a personal research analyst that captures those edges, researches an idea properly, and keeps your reasoning honest as your thinking accumulates in one place.

cupel lives in one folder, your office, and accumulates everything it learns about you there.

cupel sharpens your own reasoning, surfaces what you are missing, and recommends what it would do and why — the likely scenarios, rough upside and timeframe, with the risks named. Investing is a bet; cupel helps you make an informed one. It refuses false precision dressed as fact and bare tips with no reasoning, and never places trades; the decisions stay yours.

The stance

Edge before opinion. A familiar product or a hot tip is only a lead; it still has to survive the homework. A wonderful business at the wrong price is a poor investment. Most of a normal person’s money can sensibly sit in a low-cost index; individual picks are a considered satellite, only where you have a real edge.

002Install

Set up the office, add the skill

Install the package:

$ npm install -g @samgalanakis/cupel

Set up your office, the vault where cupel keeps everything it learns. It defaults to ~/cupel; override with CUPEL_HOME:

$ cupel init

Add the skill to your harness

cupel ships as a skill for Claude Code, Cursor, Gemini CLI, Codex, OpenCode, Kiro, Pi, Qoder, Trae, and GitHub Copilot. Install auto-detects which harness directories exist:

$ cupel skills install        # auto-detect installed harnesses
$ cupel skills install --all  # every supported provider
$ cupel skills update         # re-sync after npm update -g @samgalanakis/cupel
$ cupel skills check          # installed version + content-hash status

Then talk to it from any harness: /cupel.

Your first session. Say /cupel and, on a fresh office, it interviews you, writing your profile, edges, mandate, and a few trusted sources. Then hand it an edge-driven idea, like /cupel I keep seeing this product everywhere at work: it resumes any prior notes, researches the company, runs the discipline gate, and files a thesis with explicit falsifiers. Come back with /cupel brief any time for a status check. cupel reads and writes your office; you make every call.

Without the npm package, the skill is committed at skills/cupel/, so you can pull it straight from GitHub:

$ npx skills add SamGalanakis/cupel

Or add it as a Claude Code plugin marketplace:

/plugin marketplace add SamGalanakis/cupel
/plugin install cupel@cupel

Claude Cowork

Cowork installs plugins from a zip, not from npm. Every release ships a cupel-cowork.zip asset that bundles the CLI with zero npm dependencies, so cupel init and cupel doctor run inside the sandbox on node alone.

Download the zip, then in Cowork choose Customize, Plugins, Install, and upload it. Build it yourself with npm run build:cowork.
003The office

One folder that remembers everything

cupel keeps all of its state in one Obsidian-compatible vault, the office, never in the current project. The vault is plain markdown with YAML frontmatter for structure and [[wikilinks]] for provenance: a thesis links its [[source]]; a position links its [[thesis]].

~/cupel/ PROFILE.md brokers, currency, constraints, how you work EDGES.md your circle of competence MANDATE.md goals, risk, sizing, sell rules sources/ people and sources you trust watchlist/ ideas you are tracking positions/ what you actually hold theses/ full write-ups, one per idea journal/ a dated decision log

Open it in Obsidian for the graph view, or just read the markdown. Keep it under git: the decision journal’s value compounds as its history grows. Read the full office schema, including note types, the cupel doctor linter, and the journal discipline.

004Commands

Talk to it, or go direct

Say /cupel and it figures out what you need: it locates your office, takes its pulse, and routes you to the right job. Or name the command yourself.

onboardInterview you; write your edges, mandate, and trusted sources. The foundation.
watchTurn a seed, a source’s idea or your own hunch, into a provenance-tracked watchlist entry.
scoutBranch outward from every seed in your office, research the adjacencies for real, and return many ranked opportunities — not light conjecture.
assayTest one idea: a good business at a fair price, inside your edge?
cruxFind the single load-bearing claim a thesis rests on, and test it.
premortemAssume it failed in three years; surface the risks you are underweighting.
allocateDeploy cash or rebalance: exposure, correlation (incl. your human capital), a recommended shape.
pulseRefresh the office: sweep sources, re-check staleness, run cupel doctor.
briefA pulse plus the executive readout: what changed, what needs attention, next moves.

When you name a specific company, cupel runs cupel show <TICKER> first to resume exactly where you left off. It never starts cold on something the office already knows.

005The CLI

The filing cabinet, kept honest

The cupel binary does the deterministic bookkeeping so the LLM can do the judgment. It manages the office, validates it, and installs the skill.

initScaffold a new office at ~/cupel (or CUPEL_HOME).
wherePrint the office path so the skill knows where to read and write.
doctorCheck frontmatter, dangling links, mandate breaches, stale reviews, and reviews now due.
show <TICKER>Print every note for a ticker so a session resumes with full context.
board [A|B|C|PASS]The whole watchlist ranked by tier at a glance; filter to one tier.
tickersList every ticker the office knows; feeds scout’s dedupe.
portfolioSplit core / satellite / cash: each size, the satellite total against your target, the cash remainder. Per holding, the gain % from recorded cost-basis to last-price and a size-weighted price return — and, once capital is set, value and gain in money. Recorded prices, never live quotes.
capital [amount [currency]]Set or show your total investable capital, the single figure that lets portfolio turn allocation percentages into money. cupel never fetches account balances; you maintain it.
stamp <event>Timestamp an event (e.g. cupel stamp pulse) so the front door knows how fresh the office is.
skillsInstall, update, or check the cupel skill across your AI harnesses.

Division of labour

The LLM does the judgment; the linter guards the filing cabinet. cupel doctor catches a satellite over your max-position-pct (the core is exempt), the satellite total over its target, a large idle-cash remainder, a holding unreviewed for months, a decision whose review date has arrived, or a source long unchecked, and the companion surfaces it before you act.

006The canon

Anchored in the classics

cupel’s judgment is anchored in a small canon chosen for accessible, individual investing: Lynch and Mayer on edge, Dorsey on moats, Housel and Bernstein on temperament and risk, Bogle on humility, Graham and Marks on price. The audience is a smart person who is an expert in some other field, so the principles stay plain and free of jargon.

Read the full canon: eight thinkers as operating lenses, plus the six Lynch categories that drive the story, the numbers, and the sell signal.