---
slug: "elephant-ai"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/cklxx/elephant.ai@main/README.md"
repo: "https://github.com/cklxx/elephant.ai"
source_file: "README.md"
branch: "main"
---
elephant.ai
A leader agent for attention-heavy work.
Lives in Lark. Tracks what's moving, surfaces what matters, follows up automatically, and only pulls you in when judgment is needed.
---
## What is elephant.ai?
A **leader agent** that lives in your Lark groups and DMs. It takes ownership of work — tracking progress, following up on tasks, surfacing what needs attention, and handling coordination. Behind the scenes it orchestrates specialist agents and tools. To you, it's one reliable operator who never drops the ball.
---
## Why a leader agent?
- **Continuous ownership** — Hand off a task and it stays tracked until done.
- **Attention gating** — Compresses noise into what matters, what's at risk, and what needs your call.
- **Proactive follow-up** — Chases status, summarizes results, escalates blockers automatically.
- **Coordination absorbed** — Handles the track/ask/remind/align overhead.
- **Persistent memory** — Remembers conversations, decisions, and context across weeks and months.
- **Approval gates** — Knows when to ask before acting. Risky operations require explicit sign-off.
- **MCP extensible** — Connect any external tool through the Model Context Protocol.
- **Lark-native** — WebSocket gateway, always present in groups and DMs.
---
## Quick Start
**Prerequisites:** Go 1.24+, Node.js 20+, a Lark bot token, and an LLM API key.
```bash
# 1. Clone and build
git clone https://github.com/cklxx/elephant.ai.git && cd elephant.ai
make build
# 2. Configure (LLM key + Lark credentials)
cp examples/config/runtime-config.yaml ~/.alex/config.yaml
export LLM_API_KEY="sk-..."
alex setup # interactive first-run wizard
# 3. Start everything
alex dev up
# 4. Talk to it in Lark — or use the CLI directly
./alex "summarize the last 3 conversations and draft follow-up emails"
```
Full setup guide → [`docs/guides/quickstart.md`](https://github.com/cklxx/elephant.ai/blob/HEAD/docs/guides/quickstart.md)
---
## How It Works
```
You (Lark group or DM)
↓
Chat (lightweight LLM, ~1-3s) — instant reply, routing, ack
│
├── direct reply ──────────▶ back to you immediately
│
└── dispatch ──▶ Worker (ReAct Agent, background, minutes)
↓
Context Assembly · Memory · Policies
↓
Think → Act → Observe → Tool Execution
↓
Reply delivered to Lark (with progress updates)
```
---
## Leader Agent Features
The leader agent runs a background scheduler alongside Lark conversations. It monitors task health, generates digests, and surfaces decisions and blockers before they become problems.
| Feature | Description |
|---|---|
| **Blocker Radar** | Scans every 10 min for stale/blocked tasks. Auto-notifies with cooldown. |
| **Weekly Pulse** | Monday 9am digest: tasks completed, cycle time, token spend, success rate. |
| **Daily Summary** | End-of-day activity recap with top agents and key outcomes. |
| **1:1 Prep Brief** | Auto-generated talking points before meetings: wins, open items, blockers. |
| **Milestone Check-ins** | Hourly progress snapshots of active tasks. |
| **Attention Gate** | Per-chat message budget with urgency classification and quiet hours. |
| **Decision Memory** | Records team decisions with context. Searchable by topic, tag, date, or participant. |
Enable in `~/.alex/config.yaml`:
```yaml
proactive:
scheduler:
enabled: true
blocker_radar:
enabled: true
channel: lark
chat_id: oc_your_chat_id
weekly_pulse:
enabled: true
channel: lark
chat_id: oc_your_chat_id
```
---
## Delivery Surfaces
| Surface | Description |
|---|---|
| **Lark** *(primary)* | WebSocket gateway. Real-time progress, emoji reactions, approval flows. |
| **Web Console** | Next.js dashboard with SSE streaming, artifact rendering, cost tracking. |
| **CLI / TUI** | Interactive terminal with streaming output for local workflows. |
---
## Built-in Skills
Skills are markdown-driven workflows triggered by natural language:
| Skill | What it does |
|---|---|
| `deep-research` | Multi-step web research with source synthesis |
| `meeting-notes` | Structured summaries and action item extraction |
| `email-drafting` | Context-aware email composition |
| `ppt-deck` | Slide deck generation |
| `video-production` | Video script and production planning |
| `research-briefing` | Concise briefing documents |
| `best-practice-search` | Engineering best practice lookup |
---
## LLM Providers
```
OpenAI · Anthropic (Claude) · DeepSeek · ByteDance ARK (Doubao)
OpenRouter · Ollama (local) · Kimi · Qwen
```
Set `llm_provider: auto` — the runtime picks the best available provider from your environment keys.
---
## Architecture
```
Delivery Lark · Web Console · CLI · API Server
↓
Application Coordination · Context Assembly · Cost Control
↓
Domain ReAct Loop · Typed Events · Approval Gates
↓
Infra Multi-LLM · Memory Store · Tool Registry · Observability
```
| Layer | Key packages |
|---|---|
| Delivery | `internal/delivery/channels/lark/`, `cmd/alex-server`, `web/` |
| Agent core | `internal/{app,domain}/agent` — ReAct loop, typed events, approval gates |
| Tools | `internal/infra/tools/builtin/` — search, code, browser, files, artifacts, media |
| Memory | `internal/infra/memory/` — Postgres / file / in-memory with tokenization |
| LLM | `internal/infra/llm/` — multi-provider, auto-selection, streaming |
| MCP | `internal/infra/mcp/` — JSON-RPC servers for external integrations |
| Observability | `internal/infra/observability/` — OTel traces, Prometheus metrics, cost accounting |
---
## Documentation
| | |
|---|---|
| [Quick Start](https://github.com/cklxx/elephant.ai/blob/HEAD/docs/guides/quickstart.md) | From clone to running in minutes |
| [Configuration Reference](https://github.com/cklxx/elephant.ai/blob/HEAD/docs/reference/CONFIG.md) | Full config schema and precedence rules |
| [Architecture](https://github.com/cklxx/elephant.ai/blob/HEAD/docs/reference/ARCHITECTURE.md) | Runtime layering and execution model |
| [Deployment Guide](https://github.com/cklxx/elephant.ai/blob/HEAD/docs/operations/DEPLOYMENT.md) | Production deployment |
| [Roadmap](https://github.com/cklxx/elephant.ai/blob/HEAD/ROADMAP.md) | What's next |
---
## Contributing
Contributions are welcome. See [`CONTRIBUTING.md`](https://github.com/cklxx/elephant.ai/blob/HEAD/CONTRIBUTING.md) for development setup, code standards, and PR workflow. First time? Look for issues labeled [`good first issue`](https://github.com/cklxx/elephant.ai/issues?q=label%3A%22good+first+issue%22).
Please read [`CODE_OF_CONDUCT.md`](https://github.com/cklxx/elephant.ai/blob/HEAD/CODE_OF_CONDUCT.md) before participating, and report security vulnerabilities via [`SECURITY.md`](https://github.com/cklxx/elephant.ai/blob/HEAD/SECURITY.md).
---
## Star History
[](https://star-history.com/#cklxx/elephant.ai&Date)
---
## License
[MIT](https://github.com/cklxx/elephant.ai/tree/HEAD/LICENSE) © 2025 cklxx