1. Phase 1 (current) — Multi-turn Ollama agent with JSON tool calling: list directory, file preview, disk stats, and propose_shell_command after the model has enough context. Electron menubar + Vite web shell; planner invoked from CLI and from vite dev middleware at POST /api/plan.
2. Phase 2 (planned) — Richer read-only tools (search, metadata, git status/diff previews), tighter command normalization, and stronger destructive-action classification.
3. Phase 3 (planned) — Optional cloud-backed model routing and session memory (aligned with the paid tier story on the main site).
4. Phase 4 (planned) — Remote machine workflows, automation recipes, and long-running task orchestration.

• Frontend: Plain HTML/CSS/JS bundled with Vite. No React/Vue overhead.
• Desktop App: Electron with menubar. Transparent frameless windows.
• LLM Backend: Local Ollama API (/api/chat). Default model runs entirely offline.
• Native Bridge: Node.js standard libraries (fs/promises, child_process, os).
• Communication: Electron IPC between renderer and main; the web try-chat uses fetch('/api/plan') only when you run Vite locally (static hosts serve HTML without that API).

1. Install Ollama and run ollama pull qwen2.5:0.5b (or set HOTATE_LLM_MODEL to a model you already have).
2. Clone the repo, then npm install at the repo root.
3. Web + API: npm run dev — this repo uses port 3000 by default (vite.config.js). Try-chat and planner need this dev server; a static host serves HTML only unless you wire POST /api/plan yourself.
4. CLI smoke test: npm run cmdgen with flags you use in CI (see cli/bin.mjs --help).
5. Menubar app: npm run menubar (requires Electron deps installed).
6. Models: The DMG includes the Ollama runtime (CLI + libraries). The default model (qwen2.5:0.5b) is pulled automatically on first launch if missing (one-time download, requires internet). Shipping multi‑GB weights inside the DMG is possible but not wired yet—use CI to attach blobs if you need fully offline installs.

The website does not host the DMG for you. It points visitors at the latest GitHub Release that contains a .dmg. You create that file once per version, then publish it.

Option A — Build on your Mac

1. Clone the repo and run npm ci at the project root.
2. Run npm run menubar:pack (this runs bundle:ollama then electron-builder --mac). First run downloads the Ollama darwin bundle (~large).
3. Open the release/ folder. You’ll see something like Hotate-0.1.0-arm64.dmg (name follows package.json version and your CPU arch).

Option B — Let GitHub build it (recommended for releases)

1. Set version in package.json to the release you want (e.g. 0.1.1).
2. Commit, then create and push a matching tag: git tag v0.1.1 && git push origin v0.1.1
3. Workflow .github/workflows/release-menubar.yml runs on v* tags, builds the DMG on macos-latest, and electron-builder --publish always uploads it to a GitHub Release.
4. After the workflow finishes, the site’s Download buttons (via public/latest-dmg.js) resolve to that .dmg automatically.

If there is no release yet—or the latest release has no .dmg—the button falls back to the releases page so people can still find files manually.

The Agent Loop Flowchart

When a user asks Hotate to do something, it doesn't just blindly generate a shell script. Instead, the language model operates in a loop:

User Input -> [LLM Agent]
                 |
                 v
         Needs Context?
        /              \
     [YES]            [NO]
       |                |
       v                v
Call Read Tool    Propose Action
(e.g., ls, df)    (e.g., rm, mv)
       |                |
       v                v
 Native Node.js     User UI Preview
 Tool Execution     Accept/Reject
       |                |
       +-------<--------+
       (loop)
        

1. It reads the user's intent and the current working directory.
2. If it needs to understand the context (like checking if a file exists or seeing what is taking up space), it executes a Read-Only native Node.js tool (like list_directory). This avoids fragile shell-string parsing and OS inconsistencies.
3. It reads the tool's result directly from the filesystem and loops back to itself.
4. Once it has enough context, it either replies with a text summary or calls the Action tool (propose_shell_command) to securely queue a command for the user to approve in the UI.