Toby
Toby is an AI-assisted native macOS app and CLI for personal productivity workflows. It connects to
services such as Email, Todoist, Slack, Jira, Web Search, Apple Calendar, and
local macOS controls so you can search, summarize, organize, and act on work
from chat.
Toby combines:
- Chat-first workflows through the native macOS app
- Installable integrations shipped as
@toby/plugin-* TypeScript plugins
- Personas, skills, and memories for durable assistant context
- Schedules and daemon flows for recurring prompts or flows and inbound chat
- Listen mode for local audio recording and transcription on macOS
- CLI maintenance commands for automation, setup, backup/restore, and daemon control
Install
On macOS, install the latest release with:
curl -fsSL https://raw.githubusercontent.com/kshehadeh/toby/main/install-toby.sh | bash
The installer places toby on your PATH, installs helper binaries under
~/.toby/helpers/, installs first-party plugins under ~/.toby/plugins/, and
runs toby whisper setup for the default local transcription model.
See the help-site Install Toby
guide for manual release installs, source installs, and optional installer
settings.
Quick Start
After installing:
toby --help
toby config
toby connect email
toby
Bare toby opens the native app. Use the app for chat, configuration,
schedules, skills, and recordings.
From a source checkout:
bun install
bun run build
bun run dev -- --help
When developing plugin-backed integrations from source:
bun run build:plugins
toby plugins doctor
Module Organization
| Module | Role |
|---|
@toby/cli | Commander entrypoint for automation, setup, backup/restore, daemon, plugins, and app launch. |
@toby/core | Shared harness: chat pipeline, AI runtime, tools, integration registry, config, memory, sessions, logging, daemon-safe workflows. |
@toby/plugin-* | Installable TypeScript plugins with strict JSON stdin/stdout contracts. |
| External systems | Email, tasks, chat, work tracking, search, calendars, and local macOS APIs. |
Core is intentionally UI-agnostic. Put behavior in @toby/core when it should
work from the CLI, daemon, headless scripts, or tests without importing
React or Commander.
See docs/architecture.md and the help-site
Architecture
page for more detail.
Integrations and Plugins
First-party integrations ship as installable TypeScript plugin directories in
release archives. Fresh installs and upgrades copy them into ~/.toby/plugins/.
Current first-party plugin integrations include:
- Email
- Todoist
- Slack
- Jira
- Notion
- Apple Calendar
- Apple Reminders
- Apple Contacts
- macOS
- Sample TypeScript plugin
New plugins should be TypeScript bun-package plugins (a directory with a
manifest.json and TypeScript entrypoint). Toby discovers
toby-plugin-<name> directories, passes config on stdin, and reads one JSON
object from stdout. Legacy standalone binary plugins are still supported for
backward compatibility.
See:
Core Commands
| Command | Purpose |
|---|
toby / toby app | Open the native Toby app. |
toby config | Open the native app settings. |
toby connect <integration> | Connect an integration account. |
toby disconnect <integration> | Disconnect an integration account. |
toby status | Show connection and integration health. |
toby summarize <integration> | Summarize integration content. |
toby organize <integration> | Run integration-specific organization flows. |
toby listen | Open native app recording controls. |
toby sessions clear | Clear saved chat sessions. |
toby upgrade | Download and install the latest release. |
See docs/commands.md and the help-site
Your first chat
guide for usage details.
Documentation
The Docusaurus help site lives in apps/help-site/:
bun run docs:start
bun run docs:build
Development
Use Bun from the repo root:
bun install
bun run build
bun run lint
bun run typecheck
bun run test
Useful development commands:
bun run dev
bun run build:plugins
bun run build:executable
Notes:
- CLI tests live under
apps/cli/tests/ and should import shared harness code
from @toby/core/....
- Integration behavior should live in core/plugin modules, not in generic CLI
command branches.
Start with AGENTS.md for repository conventions and quick paths.
