灵台 LingTai

Agent Genesis — an Agent OS that gifts life

灵台，心也。 Lingtai means soul.

灵台者有持，而不知其所持，而不可持者也。 The soul holds something, yet knows not what it holds — and what it holds cannot be held. — Zhuangzi · Gengsang Chu (庄子 · 庚桑楚)

lingtai.ai · 简体中文 · 文言 · Contributing · Security · Support

---

This is the Python runtime and CLI for LingTai.

For the full experience with guided setup, use the TUI instead — brew install lingtai-ai/lingtai/lingtai-tui

Install

pip install lingtai

CLI

The lingtai-agent command is the agent runtime — it boots and runs individual agents.

# Boot an agent from its working directory
lingtai-agent run /path/to/agent/

# Check available capability providers
lingtai-agent check-caps

Agents are typically managed by the TUI, which handles initialization, lifecycle, and monitoring. The CLI is for scripting, custom agents, and programmatic use.

Architecture

This repo contains both packages. The dependency is strictly one-directional:

Package	Role
lingtai.kernel (import lingtai.kernel)	Minimal runtime — BaseAgent, intrinsics, LLM protocol, mail, logging. Zero hard dependencies.
lingtai (import lingtai)	Batteries-included — Agent with 19 capabilities, 5 LLM adapters, MCP integration, addons. Re-exports the kernel's public API.

BaseAgent              — kernel (intrinsics, sealed tool surface)
    │
Agent(BaseAgent)       — kernel + capabilities + domain tools
    │
CustomAgent(Agent)     — your domain logic

Capabilities

Perception	Action	Cognition	Network
vision — image understanding listen — speech & music web_search — web search web_read — page extraction	file — read/write/edit/glob/grep bash — shell with guardrails talk — text-to-speech compose — music generation draw — image generation video — video generation	psyche — evolving identity knowledge — private durable knowledge skills — skill catalog email — full mailbox system	avatar — spawn sub-agents (分身) daemon — parallel workers (神識)

LLM Support

Anthropic, OpenAI, Gemini, MiniMax, or any OpenAI-compatible API (DeepSeek, Grok, Qwen, GLM, Kimi).

Agent = directory

/agents/wukong/
  .agent.lock               ← exclusive lock (one process per directory)
  .agent.heartbeat          ← liveness proof
  .agent.json               ← manifest
  system/
    covenant.md             ← protected instructions (survive molts)
    pad.md                  ← working notes
  mailbox/
    inbox/                  ← received messages
    outbox/                 ← pending sends
    sent/                   ← delivery audit trail
  logs/
    events.jsonl            ← structured event log

No agent_id. The path is the identity. Agents find each other by path, communicate by writing to each other's mailbox/inbox/.

Learn more

Read the full manifesto at lingtai.ai.

Contributing

See CONTRIBUTING.md for the contribution workflow and repository navigation entry points. For responsible disclosure, read SECURITY.md; for help, read SUPPORT.md.

Acknowledgements

See docs/references/acknowledgements.md.

License

Apache-2.0 — Zesen Huang, 2025–2026

lingtai.ai · GitHub · Contributing · Security · Support · TUI