Arca Assistant：面向巴西投资者的自托管 AI 投资组合追踪器

Arca Assistant is a self-hosted, AI-powered personal finance and investment portfolio tracker built for Brazilian investors (and anyone who likes the Arca asset allocation). It consolidates stocks, REITs (FIIs), fixed income (CDB, LCI, Tesouro Direto), international ETFs, crypto and physical assets across banks and brokers, rebalances to your target allocation, and runs AI market research and long-term projections. Bring your own AI: Claude Code, OpenAI Codex (ChatGPT) or Cursor.

The Arca method (popularized by Thiago Nigro, Primo Rico) splits a portfolio equally into four "pillars": Stocks · Real estate (FIIs) · Cash / Fixed income · International (25/25/25/25). The app also ships the Arca Grão split (30/10/40/20) or your own custom targets.

✨ Features

_{Screenshots show the Portuguese UI; switch to English in Settings → Language.}

🚀 Getting started

Requirements: Node.js 20+ and one of the AIs below.

🤖 Install with your AI (copy & paste)

Open Claude Code, Codex or the Cursor agent in an empty folder and paste:

Install Arca Assistant (https://github.com/isacsneto/arca-assistant) on this computer and keep it running for me:
1. Check that Node.js 20+ and git are installed; if not, tell me how to install them on my OS and wait.
2. Clone the repository into a folder (default: ~/arca-assistant) and run "npm install".
3. Check whether an AI is ready: Claude Code ("claude auth status"), Codex ("npx codex login status") or Cursor ("agent status"). If none is logged in, ask which one I want and guide me through the login (I will run interactive logins myself).
4. Ask whether I want the app to start automatically with the computer. If yes, run "npm run local:install" (Windows, macOS or Linux) and show me the address it prints; if not, run "npm run local".
5. If Tailscale is installed, check that the https://….ts.net address opens; if "tailscale serve" asks to enable HTTPS, show me the link.
6. Open http://localhost:3001 and tell me to pick the language and the AI provider in Settings.
Do not put my financial data, passwords or API keys in commands or files (I enter those myself in the app's Settings screen). Do not expose the app to the internet: no port forwarding and no Tailscale Funnel.

⌨️ Or by hand

git clone https://github.com/isacsneto/arca-assistant.git
cd arca-assistant
npm install
npm run dev          # opens http://localhost:5173

Want to try it before adding your data? Run the demo with a fictional portfolio (port 3101, separate data):

npm run demo         # npm run demo:reset recreates the fictional data

🤖 Choose your AI

In Settings → AI provider you pick the provider and the access mode. The app shows whether each one is installed, logged in and has a key.

• Keys can be entered in the UI (stored only in data/secrets.json, outside git, and never sent to the browser) or via environment variables.
• With Claude you pick the model per task (Opus for long research, Sonnet for reading…). With Codex and Cursor, a strong model (scan and projection) and a fast one (everything else) — blank uses the CLI default.
• Reasoning effort is adjustable per task for all of them.
• The app's language (Settings → Language) also sets the language the AI writes in.

🖥️ Keep it running on your computer (free)

The cheapest option is your own computer: zero cost, the AI uses the login you already have (no API key to pay for) and your data never leaves your machine.

npm run local:install    # starts on every login (Windows, macOS or Linux) + Tailscale access
npm run local:stop       # stop now (comes back on next login; local:install starts it again)
npm run local:uninstall  # removes auto-start and tailscale serve
npm run local            # foreground, restarting if it crashes (installs nothing)

local:install builds the app, starts the server at http://localhost:3001 and restarts it if it crashes. Only one instance runs at a time, since two writing the same data/ would overwrite each other. Logs live in data/logs/server.log.

Services run as your user, so the AI uses the Claude or Codex login you already did in the terminal.

Good to know

• The computer must be on (and, on Windows and macOS, logged in). If it sleeps, the app is offline until it wakes; disable automatic sleep if you want access all the time.
• After a git pull, run npm run local:stop and npm run local:install: the app rebuilds on start.
• To develop with npm run dev, run npm run local:stop first (both use port 3001).

📱 Access from your phone with Tailscale

Tailscale creates a private network between your devices (free for personal use). The app keeps listening only on 127.0.0.1; Tailscale serves the address only to devices signed in to your account.

1. Install Tailscale on the computer running the app and sign in (Google, Microsoft, Apple or GitHub).
2. Run npm run local:install. It configures tailscale serve with HTTPS and prints the address, something like https://my-pc.tail1234.ts.net.
   • The first time, Tailscale may ask you to enable HTTPS/Serve on your tailnet: open the link it prints, confirm and run the command again.
   • The first visit can take up to a minute while the certificate is issued.
3. On your phone, install the Tailscale app (iPhone · Android), sign in with the same account and keep the VPN on.
4. Open the https://….ts.net address in your phone's browser.

Install it as an app on your home screen

• iPhone (Safari): open the address → Share button → Add to Home Screen → Add. Arca opens full screen, with its own icon, a bottom tab bar and respecting the Dynamic Island.
• Android (Chrome): open the address → ⋮ menu → Install app (or Add to home screen).

The installed app is just a shortcut to your server: with the Tailscale VPN off, or the computer off, it won't open.

🔒 Don't expose the app to the internet (router port forwarding, Tailscale Funnel, public tunnels): it has no login screen, and anyone who reaches it sees your portfolio. tailscale serve is different from Funnel: only your tailnet can see it.

Hosts like Vercel, Netlify or free Render don't work: they wipe saved files, can't run the AI CLIs and cut long tasks. If you want it 24/7 without depending on your computer, use a small VPS (or Oracle Cloud's free VM), run npm run local:install there (Linux) and reach it through Tailscale the same way.

🏦 Open Finance (optional, Brazil)

1. Create an account at meu.pluggy.ai and connect your banks (authorization happens in each bank's app).
2. In Settings → Open Finance, paste your application's Client ID and Client Secret (the app verifies them with Pluggy before saving).
3. Click Find connections (or paste each bank's itemId) and mark each one as PF or PJ.
4. Import → Open Finance → Fetch investments: review and save.

With "Use Open Finance as the source of truth" on (default), each connection mirrors the bank within its exact scope: institution + owner:

• on import, what you had at that institution and owner is replaced by what came from Open Finance;
• in the Portfolio's Update values, that scope's values come from Pluggy instead of quotes or the AI. New assets show up to be added and missing ones to be removed. You review before applying.
• Nothing outside the scope is touched. Example: a BTG PF connection replaces and updates only BTG PF. BTG PJ stays intact (with values from screenshots, text, quotes or the AI) unless you also have a BTG PJ connection returning data. A failing connection changes nothing in its scope.

Meu Pluggy's free plan covers up to 5 connections of the same owner, refreshed every 24 h. Brokers outside Brazil aren't part of Open Finance; for those, use screenshots, video or text. Credentials stay on the server only (data/secrets.json or PLUGGY_CLIENT_ID / PLUGGY_CLIENT_SECRET).

🧩 How it works

flowchart LR
  UI["React + Vite<br/>(browser / PWA)"] -- "/api" --> API["Express<br/>(127.0.0.1)"]
  API --> Tasks["Tasks<br/>read screenshots · text · scan<br/>values · projection · assets"]
  Tasks --> runAi{{"runAi()"}}
  runAi --> C["Claude<br/>Agent SDK"]
  runAi --> X["Codex<br/>codex exec --output-schema"]
  runAi --> K["Cursor<br/>agent -p --output-format json"]
  API --> Q["Yahoo Finance<br/>(quotes)"]
  API --> P["Pluggy<br/>(Open Finance)"]
  API --> D[("data/<br/>state.json · attachments · keys")]

Loading

• One AI interface, three engines. Each task asks for instructions + task + JSON schema + attachments + web search; each provider's engine translates that (native structured output on Claude and Codex; validated JSON with a retry on Cursor).
• The app does the math, not the model. The AI sets assumptions and reads documents; rebalancing, projection, value accrual and validations (negative balances, duplicates, lost items) are computed in tested code.
• You review before saving. Imports, value updates and text operations always show before → after.

📁 Tip: name your files

<institution>-<pf|pj>[-<product>] — e.g. vest-pf.png, btg-pj.pdf, itau-pf-cdb100cdi.jpg, xp_pj_lci95.png. Versions and copies (v2, copy, (2), dates) are ignored.

🔒 Privacy & security

• The server listens only on 127.0.0.1: nobody on your network can reach your portfolio.
• Everything lives in data/ (outside git): portfolio, asset attachments and API keys.
• Uploaded files go to the chosen AI at analysis time; import screenshots aren't stored.
• Each AI call is isolated: no access to your other projects, read-only, and only the tools it needs (read attachments, web search).
• Links coming from the web are filtered (http/https only); attachments get server-generated names (no path traversal).

🛠️ Development

npm test             # 169 tests (node:test + tsx)
npm run typecheck
npm run build && npm start   # local production at http://localhost:3001
API_PORT=3101 npx vite       # front-end against another instance (e.g. the demo)

shared/   rules and types (Arca, projection, import, duplicates, PF/PJ, AI, Open Finance, i18n, currencies) — tested
server/   Express, AI tasks (tasks.ts), engines in server/ai/, quotes, Pluggy, video, attachments
src/      React: Portfolio, Rebalance, Projection, Institutions, Assets, Import, Scan…
scripts/  demo with a fictional portfolio, local.mjs (always on) and per-OS services (windows/, unix/)

Adding a currency: add one entry to CURRENCIES in shared/currency.ts (symbol, name, fallback rate). Its exchange rate is fetched automatically (Yahoo EURBRL=X, AwesomeAPI EUR-BRL), and it shows up in the selectors, in the AI import schema and in Open Finance. Totals are computed in the base currency (BRL) and converted for display.

ARCA_DATA_DIR points to another data folder (that's how the demo runs without touching your data). UI strings are written in both languages in place: L("Carteira", "Portfolio") (see shared/i18n.ts).

📄 License

MIT © 2026 Isac Santos — use, modify and share freely, keeping the copyright notice. The software is provided "as is", without warranty.

Dependencies keep their own licenses: ffmpeg-static (GPL-3.0, downloaded by npm at install time, used only to read videos the browser can't open) and the Claude Agent SDK (Anthropic's terms, which each user accepts when using Claude).

_{⚠️ Disclaimer: Arca Assistant is a personal organization tool. Analyses, scans, estimates and projections are AI-generated from public data and may contain errors — they are not investment advice. Check the sources before deciding. "Arca" is the method popularized by Thiago Nigro (Primo Rico); this project is not affiliated with him, Grupo Primo or any institution mentioned.}