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

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.

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

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.

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:

• Integrations overview
• Creating a plugin
• Plugin protocol

See docs/commands.md and the help-site Your first chat guide for usage details.

• Help site: https://toby.iwonderdesigns.com/docs/intro
• Source docs index: docs/README.md
• Architecture: docs/architecture.md
• Integrations: docs/integrations.md
• Plugin protocol: docs/plugin-protocol.md
• Daemon and schedules: docs/daemon.md
• Agent/contributor guide: AGENTS.md

The Docusaurus help site lives in apps/help-site/:

bun run docs:start
bun run docs:build

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.