How helsome/folio works
Folio is a local-first desktop investment research workbench, not a trading system. The user selects a security or portfolio context in the UI, requests streamed agent research, and receives cited evidence and structured reports; findings can continue into saved theses, monitoring, and outcome tracking. Capabilities and provider adapters supply typed financial data, while shared services support research, screening, alerts, risk, and evaluation. The README documents these major branches; unsampled UI and main-process wiring is represented only where the README or excerpts support it.
Main entry points: agent-kernel.ts Agent kernel · executor.ts Capability executor · service.ts Deep research · registry.ts Capability registry
Components 28
Desktop application
- Research workbench
packages/ui/src/components - UI client
packages/ui/src/client.tsx - Electron renderer
apps/electron/src/renderer/App.tsx - Renderer IPC client
apps/electron/src/renderer/finagentClient.ts - Preload bridge
apps/electron/src/preload/index.ts - Electron main process
apps/electron/src/main/index.ts
Agent runtime
- Kernel host
apps/electron/src/main/kernelHost.ts - Agent kernel
packages/shared/src/kernel/agent-kernel.ts - Run manager
packages/shared/src/kernel/run-manager.ts - Session manager
packages/shared/src/kernel/session-manager.ts - Agent backend
packages/shared/src/agent/local-finance-agent-backend.ts - Local session storage
packages/shared/src/storage/json-file-store.ts
Data capabilities
- Capability registry
packages/shared/src/capabilities/registry.ts - Capability executor
packages/shared/src/capabilities/executor.ts - Provider router
packages/shared/src/providers/router.ts - Longbridge adapter
packages/shared/src/providers/longbridge/adapter.ts - Massive adapter
packages/shared/src/providers/massive/adapter.ts - Longbridge tools
packages/longbridge-tools/src/parser.ts
Research workflows
- Deep research
packages/shared/src/research/service.ts - Discovery screening
packages/shared/src/screening/service.ts - Research diff
packages/shared/src/research-diff/diff-service.ts - Thesis tracking
packages/shared/src/thesis/service.ts
Portfolio monitoring
- Portfolio risk
packages/shared/src/portfolio-risk/service.ts - Alert engine
packages/shared/src/alerts/engine.ts - Outcome tracking
packages/shared/src/outcome/engine.ts
Evaluation and observability
- Evaluation service
packages/shared/src/evaluation/experiment-service.ts - Evaluation backends
packages/shared/src/evaluation/backend.ts
Other components
- Investor
Connections 26
- Investor → Research workbench: selects context
README.md - Research workbench → UI client: requests operations
packages/ui/src/components/settings/useSkillToggle.ts - Electron renderer → Renderer IPC client: invokes IPC client
apps/electron/src/renderer/finagentClient.ts - Renderer IPC client → Preload bridge: calls exposed API
apps/electron/src/renderer/finagentClient.ts - Preload bridge → Electron main process: dispatches IPC
- Electron main process → Kernel host: hosts kernel
- Kernel host → Agent kernel: configures runtime
- Agent kernel → Run manager: manages runs
- Run manager → Session manager: persists sessions
packages/shared/src/kernel/run-manager.ts - Session manager → Local session storage: stores session data
- Agent kernel → Agent backend: runs agent
- Agent backend → Capability registry: uses capabilities
- Capability executor → Capability registry: executes registered
packages/shared/src/capabilities/executor.ts - Provider router → Longbridge adapter: routes provider calls
- Provider router → Massive adapter: routes provider calls
- Longbridge adapter → Longbridge tools: parses responses
- Deep research → Capability executor: fetches evidence
- Discovery screening → Capability executor: screens candidates
- Thesis tracking → Deep research: reevaluates findings
- Research diff → Thesis tracking: compares research
- Portfolio risk → Capability executor: loads financial data
packages/shared/src/portfolio-risk/service.ts - Alert engine → Capability registry: loads market status
packages/shared/src/alerts/engine.ts - Alert engine → Local session storage: persists rule events
- Outcome tracking → Deep research: tracks opinions
- Evaluation service → Agent kernel: runs benchmark cases
packages/shared/src/evaluation/experiment-service.ts - Evaluation service → Evaluation backends: records evaluations
packages/shared/src/evaluation/experiment-service.ts