Project Structure

Monorepo Layout

Agent Wilson is a monorepo with three independent packages (no workspace manager — each has its own node_modules):

agentwilson/
├── cli/              # Wilson — AI bookkeeper CLI (Bun)
├── site/             # Marketing site & skill marketplace (Vite + TanStack Start)
├── api/              # Firebase Functions backend (Node 20)
├── docs/             # Product plans and research docs
└── app/docs/         # This documentation site (Starlight)

CLI Source (cli/src/)

src/
├── index.tsx                # Entry point, CLI flag routing
├── cli.ts                   # Interactive TUI startup
├── headless.ts              # Headless mode (--run) execution
├── reports.ts               # Structured report commands (--summary, --pnl, etc.)
├── providers.ts             # Provider resolution (prefix → adapter)
│
├── agent/
│   ├── agent.ts             # Core agent loop
│   ├── scratchpad.ts        # Tool result accumulator, context management
│   └── prompts.ts           # System prompt builder
│
├── model/
│   ├── llm.ts               # Central callLlm() facade with retry
│   └── providers/           # Provider adapters (OpenAI, Anthropic, Google)
│
├── tools/
│   ├── registry.ts          # Tool registry, conditional loading
│   ├── categorize/          # AI transaction categorization
│   ├── export/              # CSV/XLSX export
│   ├── import/
│   │   ├── parsers/         # Bank-specific CSV parsers + OFX + QIF
│   │   └── detect-bank.ts   # Format detection
│   ├── query/               # Transaction search, spending summary, anomaly detection
│   └── search/              # Web search providers
│
├── skills/
│   ├── types.ts             # SkillMetadata, Skill interfaces
│   └── */SKILL.md           # Built-in skill definitions
│
├── orchestration/
│   ├── chains/              # Sequential tool pipelines
│   └── teams/               # Parallel agent execution
│
├── mcp/
│   ├── config.ts            # MCP config reader
│   ├── client.ts            # MCP server lifecycle
│   └── adapter.ts           # MCP → Wilson tool adapter
│
├── db/
│   ├── schema.ts            # SQLite schema definition
│   └── queries.ts           # Database query functions
│
├── categories/
│   └── pfc-taxonomy.ts      # Plaid PFC v2 category taxonomy
│
├── components/              # TUI components (chat log, editor, prompts)
├── controllers/             # Agent runner, model selection, input history
└── utils/                   # Shared utilities

Key Files

File	Purpose
SOUL.md	Wilson’s personality, values, anti-patterns
BRAND.md	Visual identity and design system (Forensic Noir)
env.example	Template for environment variables
src/providers.ts	Single source of truth for all 9 LLM providers
src/agent/agent.ts	The core agent loop
src/tools/registry.ts	Tool registry with conditional loading
src/skills/types.ts	Skill and SkillMetadata TypeScript interfaces
src/db/schema.ts	SQLite database schema

Tech Stack

Layer	Technology
Runtime	Bun
Language	TypeScript (ESM)
LLM orchestration	LangChain
Database	SQLite (better-sqlite3)
TUI	pi-tui
Validation	Zod
Local AI	Ollama