Skip to content
This repository was archived by the owner on Sep 3, 2026. It is now read-only.

SETUP.md

Latest commit

 

History

History
186 lines (115 loc) · 8.1 KB

SETUP.md

File metadata and controls

186 lines (115 loc) · 8.1 KB
Raw

Setup

This guide takes you from "I just clicked Use this template" to "my agent is running Tripwire on my data." It assumes you have never set up a Python project before. If you have, skip ahead. The structure is conventional.

The whole setup runs on your machine. Nothing leaves it.

What you need

  • A computer running macOS, Linux, or Windows.
  • Python 3.11. (Newer versions may work but the project is tested against 3.11. Older versions will not work; the codebase uses syntax that 3.10 and below cannot parse.)
  • An AI coding agent that can read files in a folder and run shell commands. Claude Code is the most-tested option. Codex has passed dry runs for onboarding, statement ingest, portfolio review, and thesis challenge. Gemini CLI and other runtimes are still experimental. See the runtime support matrix in README.md.
  • About 15 minutes for the first run.

Step 1: Get the repo

You have two options.

Use this as a GitHub template (recommended). On the repo's GitHub page, click Use this template > Create a new repository. Name it whatever you want. Make it private if you plan to put real data in it later. Then clone your new repo to your machine:

git clone https://github.com/<your-username>/<your-repo-name>.git
cd <your-repo-name>

Or just clone the template directly. This works if you only want to play with it locally:

git clone https://github.com/<original-template-url>.git tripwire
cd tripwire

You should now have a folder called tripwire/ (or whatever you named it) with AGENTS.md, README.md, SETUP.md, and a few subdirectories.

The rest of these instructions assume you are running commands from inside the tripwire/ folder.

Step 2: Install Python 3.11

Check whether you already have it:

python3.11 --version

If it prints Python 3.11.x, you are done with this step. Otherwise:

macOS: install via Homebrew.

brew install python@3.11

Linux (Debian/Ubuntu):

sudo apt update
sudo apt install python3.11 python3.11-venv

Windows: download the installer from python.org/downloads and pick "Python 3.11.x." During install, check the box that says "Add Python to PATH." Then open a new PowerShell window (so it picks up the PATH change) and verify:

python --version

If you see Python 3.11.x, you are good. If you have multiple Python versions installed, you may need to use py -3.11 instead of python in the commands below.

Step 3: Create a virtual environment

A virtual environment is a separate folder where this project's Python packages live, kept isolated from anything else on your machine. You make one once, and use it for every command in this project from then on.

macOS / Linux:

python3.11 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -r requirements.txt

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

This creates tripwire/.venv/ and installs Pydantic, yfinance, pytest, and a few other dependencies. The first install takes a minute or two.

The .venv/ folder is gitignored. It will not be part of your commits.

Step 4: Verify the install with pytest

Before doing anything else, run the test suite. If the tests pass, the install worked.

macOS / Linux:

.venv/bin/python -m pytest

Windows PowerShell:

.\.venv\Scripts\python.exe -m pytest

You should see a line like 109 passed in 3.4s (the exact number changes as the project evolves; the important word is passed). If you see warnings about datetime.utcnow() deprecations, that is expected on Python 3.14 and is harmless on 3.11.

If pytest fails, stop and check that you are running it through the venv. The single most common cause of trouble at this step is running plain python -m pytest against a system Python that does not have the project's dependencies. The .venv/bin/python (or .\.venv\Scripts\python.exe) prefix is not optional.

Step 5: Where your data goes

Your data lives in two folders that are gitignored. Nothing here gets committed.

  • data/ holds your inputs and structured records. Subdivided by layer: data/personal_finance/ for money, data/investment_research/ for portfolio.
  • reports/ holds generated reports (portfolio reviews, thesis challenges, periodic briefs).

You do not need to create anything in these folders by hand. The agent creates the right files in the right place when you run a workflow. If you want to drop in raw inputs (statements, screenshots, CSVs), put them in data/personal_finance/raw/ or data/investment_research/raw/.

If you want to dry-run a workflow before putting your real data in, look at docs/examples/. There is a fictional sample portfolio and thesis you can copy into a scratch folder to see how the system behaves.

Step 6: Open the repo in your agent

Open your AI coding agent and point it at the repo folder.

Claude Code: cd into the repo folder and run claude. The agent will read AGENTS.md and CLAUDE.md automatically.

Codex, Gemini CLI, or another agent that respects AGENTS.md: open the repo folder in the agent. Make sure it loads AGENTS.md as project context. (How you do this depends on the agent; check its docs.)

The agent should not need any extra setup. Tripwire's rules live in AGENTS.md and the prompts; the agent reads them and behaves accordingly.

Step 7: Your first session

Start with one sentence. The agent figures out the rest by reading the rules.

For personal finance:

"Run onboarding."

The agent will ask about your country, household, income type, and goal. Then it will look in data/personal_finance/raw/ for any files you have dropped in. If the folder is empty, it will tell you what kinds of files you can drop in (statements, CSVs, photos of paper bills) and offer a verbal-intake alternative.

For investment research:

"Help me set up my portfolio."

The agent will offer to walk you through populating data/investment_research/processed/portfolio.json from investment_research/templates/portfolio.json. Once you have a portfolio, you can ask things like:

"Research AAPL." "Review my portfolio." "Challenge my thesis on AAPL." "Weekly report."

If the agent ever does something that surprises you, that is signal worth investigating. Read AGENTS.md to see the rules it is following. The system is designed so that everything it does is auditable from data/logs/audit_log.jsonl.

Running Python commands later

Anytime you (or the agent) need to run Python in this repo, use the venv:

macOS / Linux:

.venv/bin/python -m pytest
.venv/bin/python -c "from src.hooks.validator import validate_record"

Windows PowerShell:

.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -c "from src.hooks.validator import validate_record"

Plain python (or python3 on macOS) usually points at a different Python installation that does not have the project's packages. The venv path is the one that works.

When something goes wrong

  • ModuleNotFoundError: No module named 'pydantic'. You are running Python outside the venv. Re-run the command with .venv/bin/python (macOS / Linux) or .\.venv\Scripts\python.exe (Windows).
  • TypeError mentioning float | None or int | str. You are running on Python 3.9 or older. Install 3.11 and rebuild the venv.
  • Tests fail right after install. Make sure pip installed the requirements without errors. Re-run pip install -r requirements.txt and watch for failures.
  • The agent ignores AGENTS.md. Check that your agent supports AGENTS.md as a project-context file. Claude Code does. If you are on a runtime that does not, the README support matrix is the place to start.

You are done

Once pytest is green and your agent has read the repo, the setup is finished. Everything else (loading data, running workflows, reading reports) happens through the agent.

When you want a daily-use reference, read docs/USER_MANUAL.md.