# Alloy Development Notes ## Quick Start ```bash # Make sure Rust is in your PATH (after fresh install) source $HOME/.cargo/env # Install dependencies npm install # Run in dev mode npm run tauri dev ``` ## Project Structure ``` alloy/ ├── src/ # React frontend │ ├── components/ # UI components │ │ ├── ChatInterface.tsx # Main chat UI │ │ ├── RiffView.tsx # Draft note editing │ │ ├── Sidebar.tsx # Conversation list & search │ │ └── Settings.tsx # Settings panel │ ├── services/ # Business logic │ │ ├── vault.ts # File system operations │ │ ├── riff.ts # Draft integration logic │ │ ├── server-streaming.ts # Backend stream client │ │ ├── skills/ # Skill loading and execution │ │ ├── context/ # Context window estimation │ │ └── api/ # HTTP shims for Tauri plugins (web + Tauri) │ ├── contexts/ # React contexts │ ├── hooks/ # Custom hooks │ ├── types/ # TypeScript types │ └── App.tsx # Main app component │ ├── alloy-server/ # Rust (axum) backend: model calls + tool execution │ ├── src/ # Routes, providers, tools, streaming (see its README) │ └── Cargo.toml # Rust dependencies │ ├── src-tauri/ # Tauri desktop shell (embeds alloy-server) │ ├── src/ │ │ └── lib.rs # Tauri app setup │ ├── Cargo.toml # Rust dependencies │ └── tauri.conf.json # Tauri configuration │ └── package.json # Node dependencies ``` ## Key Technologies - **Frontend**: React 19 + TypeScript + Vite - **Backend**: Tauri 2 (Rust) - **AI**: Anthropic, OpenAI, Google Gemini, xAI (Grok), Ollama - **Storage**: YAML/Markdown files (js-yaml) - **Styling**: Plain CSS ## Development Flow 1. **Frontend changes**: Hot-reloaded automatically by Vite 2. **Rust changes**: Requires rebuild (Tauri watches and rebuilds) 3. **Config changes**: May require restart ## Dual Runtime Modes The app runs in two modes: - **Tauri mode** (`npm run tauri dev`): Native desktop app. The Tauri shell embeds the Rust `alloy-server` on a random loopback port; the SPA in the webview talks to it over `/api/*`. - **Server mode** (`npm run dev`): Web browser mode at `http://localhost:1420`. One command runs the Vite frontend **and** the auto-rebuilding `alloy-server` backend (cargo-watch) together; Ctrl-C stops both. The backend's vault comes from `ALLOY_VAULT` in `.env` (override per-run with `ALLOY_VAULT=… npm run dev` or `npm run dev -- <vault>`). It binds `:3030` and Vite proxies `/api` to it. The dev port is deliberately **not** 3001, so it never collides with — or silently proxies into — an installed Alloy app holding `:3001`. Override with `ALLOY_DEV_PORT`. In both modes, model calls and tool execution happen in `alloy-server`. All builds route Tauri plugin imports to HTTP shims under `src/services/api/` (via `vite.config.ts` aliases); each shim forwards to the real native plugin under Tauri, else degrades to a browser/`/api` fallback. When adding features that use Tauri APIs or make HTTP requests, ensure they work in both modes. ## API Integration The app supports multiple AI providers. API keys are: - Stored in `config.yaml` in the user's vault - Never sent to any server except the respective provider - Loaded at startup if vault exists ## File Formats ### Conversation (YAML) ```yaml id: 2025-06-15-1750012200-bike-kickstand created: 2025-06-15T11:30:00Z model: anthropic/claude-opus-4-6 messages: - role: user timestamp: 2025-06-15T11:30:00Z content: Hello! - role: assistant timestamp: 2025-06-15T11:30:05Z content: Hi there! ``` ### Config (YAML) ```yaml defaultModel: anthropic/claude-sonnet-4-6 ANTHROPIC_API_KEY: sk-ant-... OPENAI_API_KEY: sk-... GEMINI_API_KEY: ... XAI_API_KEY: xai-... OLLAMA_BASE_URL: http://localhost:11434 # Optional SERPER_API_KEY: ... SONIOX_API_KEY: ... ``` ### Memory (Markdown) ```markdown # Memory ## About me - Your context here ## Preferences - Your preferences here ``` ## Building for Production ```bash npm run tauri build ``` Output locations (macOS): - DMG: `src-tauri/target/release/bundle/dmg/` - App: `src-tauri/target/release/bundle/macos/` ## Debugging ### Frontend Console Open DevTools in the Tauri window (right-click → Inspect Element) ### Rust Logs Check terminal where you ran `npm run tauri dev` ### File Operations All vault operations can be inspected by looking at the files in your vault folder ## Tips - **Fast iteration**: Keep `npm run tauri dev` running - **Test persistence**: Check your vault folder to verify files - **Web mode**: `npm run dev` for faster iteration — Vite frontend + auto-rebuilding `alloy-server` on :3030, one command (vault from `.env`) - **Search**: Works across all message content in all conversations - **Memory**: Edit `memory.md` to customize AI context ## Common Issues **Build fails**: Make sure Rust is installed and in PATH **API errors**: Check your API keys in `config.yaml` or the Settings panel **Files not saving**: Verify vault folder permissions **Search not working**: Check that conversations have loaded --- Built with lateral thinking & withered technology