A local-first GitHub template that turns your AI coding agent into a personal research analyst and portfolio skeptic.
You bring an agent. Tripwire brings the rules it operates under, the data contracts it writes through, and the prompts that decide what good output looks like.
Most investing tools cheerlead. They tell you your portfolio is great, your thesis is sound, your risk is appropriate. That is not useful when you are about to make a decision with real money.
Tripwire pushes back. Before it agrees with anything, it has to steelman the opposite. Before it writes a research brief, it has to lead with what would falsify the thesis. Before it tells you a position looks fine, it has to surface the disconfirming evidence first.
The flagship output is not a price target. It is a tripwire: an observable, measurable condition that, if it occurs, should cause you to reconsider. "If services gross margin drops below 65% for two consecutive quarters" is a tripwire. "The stock might fall" is not.
This is a template, not a product. You fork it, drop your own data in, and your agent runs the system by reading the rules in AGENTS.md.
Two layers, both shipped in every clone.
Layer 1: personal finance. Onboarding from messy real-world inputs (CSVs, screenshots, statements). Income, expenses, debts, assets. Budget review. Risk profile. Bills and reminders. The point is an accurate, audited picture of your money, not advice about what to do with it.
Layer 2: investment research. Portfolio tracking. Per-ticker research briefs that lead with disconfirming evidence. Theses you write that the agent then attacks. Portfolio reviews that flag concentration, drift, and missing theses. Weekly and monthly summaries written like a PM brief, not a dashboard.
Every structured record carries provenance (who created it, when, was the user's say-so behind it, how confident was the agent). Every write to user data goes through a validate-then-log pipeline. The audit log is append-only.
People who want their AI tools to argue with them about money decisions.
You do not need to be technical. You do not need to write code or run Python commands. You open your agent, say one sentence in plain English ("review my portfolio," "challenge my thesis on AAPL," "run onboarding"), and the agent does the rest by reading the repo's rules.
You do need to be willing to write a thesis. The agent cannot challenge a position you have not articulated.
Your data stays on your machine.
data/,reports/, and.envare in.gitignore. They never get committed.- The repo contains zero code that calls an external AI API. There is no telemetry. No background sync. No cloud anything.
- You can still run Tripwire with an API-backed agent (Claude, Codex, Gemini, anything that reads
AGENTS.md). That is a runtime choice you make and configure yourself. The repo does not require it.
If you ever notice the agent suggesting a write that would put data outside data/ or reports/, stop it. That is a bug in the prompt, not a feature.
Full setup is in SETUP.md. The short version:
- Click "Use this template" on GitHub, or clone the repo.
- Install Python 3.11.
- Create a virtual environment in
tripwire/.venv/and install the requirements. - Open the repo in your agent (Claude Code, for example) and say "run onboarding" or "research AAPL."
The agent reads AGENTS.md, follows its rules, and writes only inside data/ and reports/.
| Runtime | Status |
|---|---|
| Claude (Claude Code, Claude Desktop) | Recommended. The system has been built and tested against Claude end to end. |
| Codex | Tested on dry runs for onboarding, statement ingest, portfolio review, and thesis challenge. More verbose than Claude in testing, but the audit and epistemic rules held. |
| Gemini CLI | Experimental. Reads AGENTS.md directly. Untested against the full workflow set. |
Other agents that read AGENTS.md |
Experimental. Anything that respects an AGENTS.md constitution should work; the repo ships no runtime-specific code paths. |
Multiple agents can coexist in the same clone. You never have to rename files to switch.
If you run a workflow on a non-Claude runtime and it does something unexpected, that is signal worth reporting. The product target is agent-neutral; gaps are bugs.
- Execute trades or connect to a brokerage.
- Recommend buying, selling, or holding anything.
- Predict prices, returns, or direction.
- Estimate taxes.
- Backtest strategies.
- Handle options, crypto, or derivatives in any depth (track them as line items only).
- Sync, share, or upload your data anywhere.
If you ask the agent "should I sell?" it will decline and reframe: here is what the evidence suggests, here are the tripwires, here are the questions it cannot answer. You decide.
docs/USER_MANUAL.md. Day-to-day guide for running workflows, reading outputs, and checking the audit log.SETUP.md. Install, first session, test verification.AGENTS.md. The operating constitution your agent reads. Hooks, provenance, routing, epistemic standards.docs/epistemic-design.md. Why the system is built around tripwires, steelmanning, disconfirming evidence, and refusal behavior.docs/examples/. Sample portfolio, thesis, research brief, portfolio review, and weekly report. All fictional.
Tripwire is a research and organization tool. Its outputs are generated by an AI system following the rules in this repo. They are not financial advice. They are not produced by a licensed advisor. They will sometimes be wrong.
Verify independently before acting on anything. You are responsible for every decision you make with your money.