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. Discipline, not prediction: it does not predict prices, place trades, or give buy or sell calls.

001Start

A cupel is where you find the gold

A cupel is the bone-ash vessel used in fire assay. You melt a sample in it under heat and the base metal burns away into the ash, leaving a bright bead of pure gold or silver. The dross goes; what is truly valuable stays.

cupel does that for your investing ideas. It turns the LLM in your AI harness into a personal research analyst: a stateful companion that learns your edges and stress-tests your ideas against the investing canon. The premise is Peter Lynch’s, that your advantage is what you already know from your work and your life. cupel’s job is to capture that edge, turn it into disciplined ideas, and keep you honest.

cupel is not a stock screener and not a per-project linter. It is a companion that lives in one folder, your office, and amasses everything it learns about you there.

Detection and discipline only. cupel sharpens your own reasoning and surfaces what you are missing. It does not predict prices, place trades, or give buy or sell calls.

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 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 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.
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.
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.
portfolioSum positions: each size against the cap, the total against your satellite target.
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 position over your max-position-pct (or the whole satellite over its target), 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.