Lush is a spec-driven framework for building, running, and deploying AI agents. Define agents in YAML, wire in tools via MCP, schedule autonomous loops, and ship to production — all from a single project directory versioned in git.

# agents/helper/spec.yaml
name: helper
model: gemini-2.5-flash
description: You are a helpful assistant that answers questions concisely.

$ lushctl chat helper
🟢 helper (gemini-2.5-flash)

You: What's the capital of France?
helper: Paris.

There's a gap between no-code agent builders and raw agent frameworks. No-code tools handle greenfield apps but break down when you need version control, code review, and production infrastructure. Raw frameworks give you full control but leave deployment, scheduling, security, and observability as exercises for the reader.

Lush fills this gap. It is to agent development what build tools like Vite are to web development: an opinionated, spec-driven workflow that catches errors early, provides a great local dev experience, and produces artifacts you can deploy anywhere.

Specs are canonical. Everything — behavior, tools, permissions, schedules — lives in YAML files in git. No config drift. No permissions diverging from reviewed deployments.

Build catches errors early. Invalid tool references, missing agents, undeclared service accounts — all caught at lushctl build before anything reaches production.

Preview before shipping. Write tools are stubbed by default so you can observe agent behavior before enabling live side effects.

Self-hostable. lushctl serve runs your agents as a standard Bun process. Deploy with Docker, Kubernetes, or any platform that runs containers.

• Bun (v1.1+)
• A Google AI API key for Gemini

lushctl init my-agents
cd my-agents
export GOOGLE_API_KEY="your-key-here"

This scaffolds the canonical project structure:

my-agents/
├── agents/
│   └── helper/
│       └── spec.yaml
├── lush.yaml
├── package.json
└── .gitignore

Interactive mode:

lushctl chat helper

Pipe mode (for scripting and CI):

echo "Summarize this README" | lushctl chat helper

Agents can use MCP servers and custom TypeScript functions:

# agents/file-reader/spec.yaml
name: file-reader
model: gemini-2.5-flash
description: You help users understand codebases.
tools:
  - server: mcp://npx/@anthropic-ai/mcp-filesystem
    access: read

// tools/lookup-weather.ts
import { defineTool } from '@lush-agents/runtime';

export default defineTool({
  name: 'lookup_weather',
  description: 'Get current weather for a city',
  parameters: { city: { type: 'string', description: 'City name' } },
  execute: async ({ city }) => {
    const res = await fetch(`https://wttr.in/${city}?format=j1`);
    return res.json();
  },
});

lushctl build

The build step validates all specs — model names, tool references, loop schedules, ACL consistency — and produces a content-addressed manifest.

lushctl run

Starts all agents, loops, a web chat UI, API server, and trace viewer at http://localhost:3141. Specs hot-reload on save.

# loops/daily-digest.yaml
name: daily-digest
schedule: "0 9 * * *"
agent: helper
run_as: serviceaccount:digest-bot
instruction: |
  Summarize the top 3 Hacker News stories from today.

lushctl loop trigger daily-digest

lushctl build
lushctl serve

lushctl serve runs your agents as a production-ready Bun process — no dev UI, no file watcher, just agents, loops, and API endpoints. Containerize it and deploy anywhere.

my-project/
├── agents/
│   └── [name]/
│       └── spec.yaml       # Agent definition
├── loops/
│   └── [name].yaml          # Scheduled agent invocations
├── tools/
│   └── [name].ts            # Custom TypeScript tools
├── skills/
│   └── [auto-populated]     # Installed skill definitions
├── skills.lock               # Pinned skill versions
└── lush.yaml             # Project config: service accounts, tool grants

• Architecture — how lush works under the hood
• Roadmap — milestone-driven development plan

Apache 2.0 — see LICENSE.