zeno-framework

A modular Python framework for building AI assistants. Bring an LLM, plug in channels (CLI, email, iMessage), wire memory adapters (SQLite, Chroma, Qdrant), and ship.

zeno-framework is a meta-package — it ships no code of its own and pulls in the right combination of zeno-* packages via extras.

Install

# minimal core — ships the Claude provider by default
uv add zeno-framework

# terminal chat with memory
uv add 'zeno-framework[memory,cli]'

# OpenAI-compatible provider on top of the default Claude provider
uv add 'zeno-framework[openai]'

# the full kitchen sink
uv add 'zeno-framework[all]'

Python 3.12+ required.

By default, pip install zeno-framework installs zeno-provider-claude so ClaudeSDKProvider works out of the box. To use OpenAI-compatible endpoints (OpenAI, OpenRouter, LiteLLM, Azure v1, Ollama, vLLM), add the openai extra. The claude extra is also declared for explicit installs but is redundant with the default.

Hello world

import asyncio

from zeno.agent import Agent
from zeno.app import ZenoApp
from zeno.channels.cli.channel import CliChannel
from zeno.providers.claude_sdk import ClaudeSDKProvider


async def main() -> None:
    app = ZenoApp(
        agent=Agent(
            name="root",
            instructions="You are a helpful assistant.",
        ),
        channels=[CliChannel()],
        provider=ClaudeSDKProvider(),
    )
    await app.run()


asyncio.run(main())

export ANTHROPIC_API_KEY=sk-ant-...
uv run python hello.py

That's a working terminal-chat assistant. Add memory, more channels, or swap the provider as you grow.

Extras

zeno-core is always installed — it provides the Agent, ZenoApp, Ctx, @tool, provider/channel protocols, and the turn worker.

What's in the framework

• Agents and sub-agents — a root Agent orchestrates and delegates to specialist SubAgent instances. Each sub-agent declares its own tools, built_in_tools, and max_turns; the Claude provider translates them to native dispatch via the SDK's Task tool. See the "Composing specialists" section in the root README.
• Tools — @tool decorator with auto-injection of Ctx, secrets, and memory binders.
• Channels — pluggable transports (CliChannel, EmailChannel, SendblueChannel); contributed via the zeno.channels entry-point group.
• Providers — ClaudeSDKProvider (default) and OpenAIProvider; contributed via the zeno.providers entry-point group.
• Memory — three-layer model (session, conversation, user memory) with SQLite defaults and pluggable vector knowledge stores.
• Scheduler — proactive triggers for cron/heartbeat workflows.
• Secrets — SecretsStore protocol with env-var default and optional 1Password adapter.

See the example chat app for a complete reference implementation in ≤150 lines.

Links

• Source code & issues: https://github.com/nkootstra/zeno
• Changelog: https://github.com/nkootstra/zeno/blob/main/CHANGELOG.md
• Security policy: https://github.com/nkootstra/zeno/blob/main/SECURITY.md
• Contributing: https://github.com/nkootstra/zeno/blob/main/CONTRIBUTING.md

MIT licensed.