The Froots manual.

Froots is a local-first workspace that pairs a markdown editor with an always-on agent. Notes, conversations, scheduled routines, native widgets, and 60+ skills, all running on your machine. This page is the full feature tour — read end to end, or jump to a section in the sidebar.

Install

Pick your OS on the downloads page. The macOS build is signed and notarized; the Windows build is EV-signed; the Linux AppImage runs on any reasonably modern distro. Or install from your package manager:

# macOS
brew install froots/tap/froots
# Windows
winget install Froots.Froots
# Linux
curl -fsSL froots.app/install | sh

First launch

The first time Froots opens it creates a workspace at ~/Library/Application Support/com.motivex.desktop/workspace on macOS (and the equivalent on Windows / Linux). Inside that folder you'll find kb/ for your knowledge base, memory/ for the agent's memory files, and persona/ for identity. You can browse and edit these in any editor — Froots watches the disk and refreshes live.

Models & BYOK

Froots speaks Claude (Anthropic), Codex (OpenAI), and Pi (any OpenAI-compatible endpoint, including Ollama on localhost). Open Settings → Models to pick a backend and paste a key. Keys live in your OS keychain; they never touch a Froots server.

# From the command palette
/model set anthropic sk-ant-…
/model default claude-opus-4-7

Memory

Memory is what makes the agent feel like it knows you. Three plain markdown files capture the running state of your work; a semantic index makes them searchable in milliseconds.

The three files

Open the Memories tab in the sidebar to see and edit them inline:

• context.md — what you're focused on right now, what you're watching, a rolling session log.
• decisions.md — choices you've made and don't want the agent to second-guess (architecture calls, tone preferences, vendor picks).
• learnings.md — things you or the agent figured out the hard way and want to remember next time.

Edits autosave. Each file is just markdown on disk — open it in your favourite editor and Froots picks up the change live.

Indexed memories

Behind the markdown, every section is chunked, embedded with a local BGE-small model (384 dimensions), and stored in a libSQL database with a DiskANN index. The agent retrieves relevant chunks on every turn; you can search them by hand from Settings → Memory:

# Filter by category
category: user_profile, decisions, learnings, notes
# See similarity scores + retrieval frequency
sort: most-retrieved

Privacy & control

Memory never leaves your machine. The embedding model runs locally; the index is a SQLite file. Delete a single chunk from the Memory settings, or wipe the whole memory folder — the next agent turn just won't have those memories. Nothing syncs unless you set up sync explicitly.

KB Editor

The KB (knowledge base) is your vault: a tree of markdown files you write, link, and search. The editor is a Tiptap WYSIWYG surface — typing feels like Notion, but the file on disk is plain markdown.

Vault & file tree

Files live under workspace/kb/. Open the file tree from the sidebar, or pop a docked tree panel with ⌘\. Right-click any file or folder to rename, delete, or create a new note inside it. The tree refreshes live when the agent (or any other app) writes to disk — no polling, no stale state.

Editing

The toolbar covers the basics: bold, italic, underline, strikethrough, inline code; headings, quotes, lists, tasks. Autosave fires 800ms after you stop typing; ⌘S forces an immediate save. A small "Saved" pill in the corner tells you you're caught up.

Tables, code blocks, math, drawings (Excalidraw-style), and embedded widgets all render inline. If you edit the file outside Froots while you have unsaved changes, a banner offers reload or discard.

Wiki-links

Type [[ and Froots autocompletes against the vault. Click any wiki-link to jump to the target page. Broken links don't error — they just sit there until you create the page they point at.

Slash commands

Type / at the start of a line to open the block menu: heading, list, task list, code block, table, divider, drawing, widget embed. The same menu is keyboard-navigable — type a few letters and hit Enter.

Conversations

Conversations are how you actually talk to the agent. Every conversation is a session, persisted to a local SQLite store, with full tool-execution history.

Sessions

The Conversations view groups sessions into Pinned, Background (running async), and Recents. Each session shows a status badge — running, idle, completed, error — plus its intent line. Pin to keep around forever; delete from the right-click menu.

Model selection

Pick a model per session from the chip below the composer. Token estimates render live (Claude 200k, GPT-4 128k, Gemini 1M). Streaming responses auto-scroll, but if you scroll up to read something, a jump to latest button appears so you don't get yanked back.

Tools & plan mode

When the agent calls a tool — search the vault, run a skill, edit a file — the call shows up as a collapsible bubble with the input JSON, the output, and success/error state. Plan mode lets the agent propose a multi-step plan and wait for your approval before doing anything destructive.

Side-band panel

Press ⌘J to open a 380px chat panel docked to the right of any KB page. The panel scopes itself to the current document — switch files and a new conversation begins (the previous one is saved automatically). Useful for "explain this paragraph" without leaving the page.

Routines

A routine is a scheduled prompt. Type the prompt once, attach a schedule, and the agent runs it on time without you. Routines can be a single prompt or a multi-step flow with branches.

Library presets

Open Library → Routines for 13 categories of presets: morning brief, wake / bedtime, smart home, comms, chores, errands, family, wellbeing, KB, standups, repo, release, research. Each preset is a starting point you can edit before saving.

Schedules

Five schedule types:

• Daily — every day at a fixed time (e.g. 08:00).
• Weekly — chosen days of the week.
• Interval — every N minutes.
• Cron — full cron expression for the picky.
• Once — fire at a specific timestamp and never again.

You can also hit Run now on any routine to fire it immediately, regardless of schedule.

Multi-step flows

Routines aren't just single prompts. The flow editor (built on ReactFlow) lets you chain steps: a prompt, a delay, a condition branch. Drag connections between cards; auto-layout keeps the canvas tidy.

Run history

Each routine keeps the last 50 runs: status (completed / submitted / failed), duration, error if any, started-at timestamp. Click a run to inspect what the agent did. If a run goes wrong, errors are kept verbatim — no friendly-but-useless wrapping.

Skills

Skills are how the agent does things in the world. There are 60+ shipped today, ranging from github and blender to apple-notes, sonos, bluebubbles, and 1password.

What is a skill

A skill is a folder under skills/ with a SKILL.md manifest, optional installer scripts, and reference assets. When you enable a skill, its tools register with the agent's MCP-like tool registry. The agent can then call them — usually with explicit user approval the first time.

SKILL.md format

The manifest is YAML frontmatter plus markdown:

---
name: apple-notes
emoji: "📝"
description: "Read and write Apple Notes via AppleScript"
platforms: [macOS]
requires:
  bin: [osascript]
install:
  brew: apple-notes-cli
---
# Apple Notes
The agent can list, read, and write notes…

Permissions

Permission has two layers:

• Eligibility — does this skill have its dependencies installed? If not, the toggle is greyed out and the badge reads blocked.
• Approval — sensitive tools (anything that writes outside the vault, sends a message, or runs shell) prompt with the persona-write confirmation modal before executing. Esc denies, Enter approves.

Trust levels in Settings → Permissions let you set a default — Careful (always ask), Balanced (ask for sensitive tools), Yolo (only ask for destructive ones).

The catalog

Open Settings → Skills to browse, search, install, and toggle. A handful of system skills are always on; the rest are off by default. Each skill entry shows its dependencies, a description, and tabs for scripts / references / assets.

Heartbeat

Heartbeat is the always-on agent that runs in the background even when you're not asking it anything. Every N minutes it wakes up, looks at your context, and decides whether something is worth surfacing.

What it does

The heartbeat reads memory/context.md (your current focus, what you're watching, the recent session log) and runs a meta-prompt that decides: is there something the user should know about right now? If yes, it calls notify_user and you get a desktop notification. If no, it exits silently. Bias is firmly toward silence.

Cadence & meta-prompt

Pick a cadence in Settings → Heartbeat — 15, 30, 60, or 120 minutes. The default meta-prompt is well-tuned: read context, optionally prune session-log entries older than seven days, decide whether anything warrants surfacing. Power users can edit the meta-prompt; most shouldn't need to.

Proactive notifications

Notifications surface as native OS toasts (and an in-app inbox). Click one to open the relevant note or session. The settings panel also shows the last fired time, the last error if any, and a Fire now button so you can sanity-check the loop end-to-end.

Identity (Persona)

The agent's identity lives in four markdown files. Editing them changes how the agent behaves on the next turn — there is no separate "personality" config or model fine-tune.

The four files

• SOUL.md — values, behavioural guidelines, hard rules. The agent's character.
• IDENTITY.md — name, creature type, vibe. The agent's face.
• USER.md — your profile: who you are, your role, your preferences, your tools. The agent's mental model of you.
• BOOTSTRAP.md — the setting and current focus. Lightweight context the agent uses to bias its first reply.

Open Settings → Persona for an inline editor. The files are protected — anything outside the persona folder cannot edit them.

Approval flow

When the agent (or a skill) tries to write to persona/*.md, the approval modal appears: a shield icon, a one-line summary of the proposed change, the file path, and a queue counter if multiple approvals are pending. Esc denies and the agent keeps going as if the change had never been proposed.

Contacts (Guardians)

Contacts — internally called guardians — are people you grant scoped access to your assistant. A guardian can message the agent through a channel (iMessage, Telegram, Slack, etc.), and the agent treats their messages with whatever permissions you set.

Channels

Eight channels are supported today: iMessage, Telegram, Signal, Slack, WhatsApp, Gmail, Email (generic SMTP/IMAP), and X (Twitter DMs). Each requires a backing skill to be installed and enabled — channels you haven't configured stay greyed out.

Pairing & verification

Adding a guardian goes:

1. Pick the channel and enter their handle (phone, user ID, email — Froots canonicalises automatically).
2. Froots generates a 6-digit pairing code valid for one hour.
3. The guardian sends the code back through the channel; their identity flips to verified.

The flow lives in the Add Contact dialog under Assistant → Contacts.

Permissions

Five per-guardian permissions, each independent:

• send_messages — can write to the agent at all.
• approve_actions — can approve sensitive tool calls on your behalf.
• delegate_tasks — can hand the agent a routine to run.
• read_memories — can ask the agent things that require pulling from memory/.
• relay_to_guardians — can route messages on to other guardians (e.g. a manager triaging requests).

Widgets

Widgets are glanceable surfaces — focal numbers, gauges, sparklines, action buttons — generated on demand by the agent. They render natively on macOS (WidgetKit) and Windows (Widget Board), and inside Froots itself.

Native & in-app

Three surfaces, one source of truth (a JSON layout tree per widget):

• macOS WidgetKit — small, medium, and large families on the home screen and Notification Center. Native rendering shipping; build pipeline integration in progress.
• Windows Widget Board — Adaptive Card 1.6 rendering. Skeleton in place; full COM provider in progress.
• In-app — the home page pinned strip and Settings → Widgets gallery. Shipping today, including primitives (ring, chart) that don't render on native OS surfaces.

Layout primitives

Ten node types compose any widget: vstack, hstack, text, gauge, ring, chart, image, action, spacer, divider. Each widget declares a family (small / medium / large) and a tree of these nodes. The renderer turns that tree into SwiftUI on macOS, Adaptive Cards on Windows, and React components in-app — no per-platform code required.

Agent-generated

You don't author widgets by hand. You ask the agent for one — "give me a widget for my deploy pipeline" — and it calls the suggest_widget tool with a proposed layout. Approve, and it calls generate_widget to write the JSON to disk; macOS reloads timelines, Windows refreshes its board, the in-app view updates immediately. Edits go through the same loop.

Action buttons deep-link via motivex://action/{verb}, so a "Run brief" button on your phone widget can fire the actual brief routine on your desktop.

Settings

Settings is nine panels, all in one modal. Open it from the gear in the topbar.

All nine panels

Memory, Skills, Persona, Heartbeat, Widgets, and Scheduled tasks are not duplicated here — they live in their own sidebar entries so the deep config stays close to the feature it configures.