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.

# 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

---

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:

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	From clone to running in minutes
Configuration Reference	Full config schema and precedence rules
Architecture	Runtime layering and execution model
Deployment Guide	Production deployment
Roadmap	What's next

---

Contributing

Contributions are welcome. See CONTRIBUTING.md for development setup, code standards, and PR workflow. First time? Look for issues labeled good first issue.

Please read CODE_OF_CONDUCT.md before participating, and report security vulnerabilities via SECURITY.md.

---

Star History

---

License

MIT © 2025 cklxx