lvndry/jazz

Jazz is an agent harness: the loop, guardrails, and surfaces that turn a model into an agent you can run unattended. You define the agent: primary and companion models, a persona, tools, and permissions in one JSON file, and Jazz runs it in your terminal, from scripts, on a schedule, or behind a Telegram or Discord bot you own. Out of the box an agent works with your files, git, and the web; connect an inbox, an Obsidian vault, or a search provider and it grows into an everyday assistant.

Install it once and it runs everywhere. A terminal REPL, a one-shot command inside a script, a scheduled workflow, a GitHub Action that reviews your pull requests, or a Telegram and Discord bot on a server you own. Same agent, same tools, same memory. In a bot conversation it asks you right there when a job needs your permission; anywhere else it parks the job and tells you on your phone through a notify target, where you can approve it from chat.

25 providers are supported, including OpenAI (with an API key or a ChatGPT Plus/Pro plan), Anthropic (with an API key or your own Claude Code sign-in), Google, Mistral, Groq, and OpenRouter, plus ollama, llama.cpp, vllm, and sglang for self-hosted models with no API key unless the server requires one. Everything else connects through MCP.

One agent can compose different models by capability: keep the model you trust for reasoning and tools, then bind separate companions for image, audio, and video understanding or generation. The persona, memory, permissions, and surface stay the same while each medium goes to the model best suited to it.

Get started

curl -fsSL https://github.com/lvndry/jazz/releases/latest/download/install.sh | bash
jazz

That installs a single self-contained binary into ~/.local/bin: no Node, no npm, nothing else to install. Set JAZZ_INSTALL_DIR to put it somewhere else. If you would rather go through npm:

npm install -g jazz-ai
jazz

Either way, jazz update upgrades in place.

Jazz walks you through provider setup on first run. It can cost nothing: OpenRouter's free models router needs no credit card, and ollama runs entirely on your own hardware.

Then ask it for what you want. These work the moment the wizard finishes: no extra keys, no extra installs:

> give me the TL;DR of ~/Desktop/bitcoin.pdf
> review the last 5 commits and flag anything risky
> fetch https://en.wikipedia.org/wiki/Jazz and give me the short version

When provider pricing is known, Jazz reports the estimated cost; providers that return a billed amount can report their actual per-call charge. Unknown pricing is marked unknown rather than presented as free.

With a minute of setup each, Jazz also does the bigger jobs:

> check my unread email, summarize what matters, archive the rest         # after `himalaya` is configured
> deep-research the Three-Body Problem and write it into my Obsidian vault # after a web-search key is set
> every morning at 7, tell me the weather and what to wear                 # as a scheduled workflow

The guides walk through complete setups.

Where it runs

Surface	How you run it
Terminal	jazz
Scripts & pipes	jazz run --json --agent dev "…"
Cron / launchd	jazz workflow schedule <name>
GitHub PRs & Actions	.github/jazz/, reviews every PR in this repo
Telegram	packages/telegram-bot/, docker compose up
Discord	packages/discord-bot/, docker compose up
iMessage	jazz imessage (hosted Photon line) or jazz imessage --local (your Mac account)
WhatsApp	packages/whatsapp-bot/, jazz whatsapp
Your SSH server	/detach <host> in chat, then jazz detach attach <id>

Slack, Google Chat, or your own app work the same way. See Chat platforms.

Documentation

Start at docs/index.md.

• Getting started: install, first run, and first custom agent
• Concepts: agents, tools, memory, automation, companions, and remote work
• Surfaces: terminal, headless, schedules, CI, chat, webhooks, and peers
• Guides: complete setups you can run
• Security: permissions, approvals, secrets, egress, and remote access
• Configure: models, agents, workflows, MCP, search, and telemetry
• Maintainers: code-backed architecture and runtime traces

Community

Discord · Discussions · Issues · Contributing · Security

MIT licensed. See LICENSE.