Lingtai Agent

Agent Genesis — an Agent OS that gifts life

Lingtai means soul — the innermost seat of the heart-mind.

"The soul holds something, yet knows not what it holds — and what it holds cannot be held." — Zhuangzi, Gengsang Chu

English | 中文 | 文言 | lingtai.ai

---

A Unix-style Agent OS — agent is filesystem, filesystem is agent.

Agents spawn avatars, avatars spawn avatars. The network IS the product.

Orchestration as a Service.

Quick start

brew install lingtai-ai/lingtai/lingtai-tui
lingtai-tui

The TUI bootstraps everything — Python runtime, dependencies, and a guided setup on first launch. Choose the Adaptive recipe (recommended) for progressive feature discovery, or Tutorial for a step-by-step walkthrough. Use a dark terminal for the best experience. Text selection: hold Option (macOS/iTerm2) or Shift (Windows Terminal/Linux). Ctrl+E opens an external editor.

First time? Install Homebrew first

macOS:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Linux / WSL:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
sudo apt install build-essential

Then run the brew install command above.

Install from source (latest main, no release needed)

curl -sSL https://raw.githubusercontent.com/Lingtai-AI/lingtai/main/install.sh | bash

Clones, builds, and installs lingtai-tui (and lingtai-portal if npm is available) to your Homebrew prefix. Use this to get unreleased changes across machines without cutting a release. To revert: brew reinstall lingtai-tui.

Install a specific branch or tag:

curl -sSL https://raw.githubusercontent.com/Lingtai-AI/lingtai/main/install.sh | bash -s -- --ref v0.4.43

Requires Go 1.24+ and git. Node.js needed for portal only.

The script auto-detects mainland China networks and switches to domestic Go/npm mirrors (goproxy.cn, registry.npmmirror.com) when proxy.golang.org is unreachable. Users elsewhere see no difference.

Mainland China: speed up Homebrew itself with the Tsinghua mirror (中国大陆)

If brew install / brew update stalls pulling the homebrew-core index or downloading bottles (which come from ghcr.io and are often unreachable from CN networks), point Homebrew at Tsinghua's TUNA mirror before installing:

# Set for this shell and persist in ~/.zprofile (macOS default shell).
# Bash users: replace ~/.zprofile with ~/.bash_profile.
cat >> ~/.zprofile <<'EOF'
export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
EOF
source ~/.zprofile
brew update

Then run the normal brew install lingtai-ai/lingtai/lingtai-tui. This is independent of the Gitee tap below — the Tsinghua mirror accelerates Homebrew's own infrastructure (bottles, core index), while the Gitee tap only helps when the brew tap step for this project's formula fails.

Mainland China: use Gitee tap if GitHub is unreliable (中国大陆)

If brew install lingtai-ai/lingtai/lingtai-tui fails at the brew tap step (e.g., GnuTLS / TLS errors cloning from GitHub), use the Gitee-mirrored tap instead:

brew tap lingtai-ai/lingtai https://gitee.com/huangzesen1997/homebrew-lingtai.git
brew install lingtai-ai/lingtai/lingtai-tui

The formula is identical to the GitHub tap — it auto-detects CN networks and uses goproxy.cn + registry.npmmirror.com for build dependencies. The Gitee tap is a mirror, so formula updates may lag GitHub by a few hours.

Build from source manually (requires Go 1.24+)

# Replace v0.5.2 with the latest version
VERSION=v0.5.2

curl -L "https://github.com/Lingtai-AI/lingtai/archive/refs/tags/${VERSION}.tar.gz" -o lingtai.tar.gz
tar xzf lingtai.tar.gz
cd "lingtai-${VERSION}/tui"

go build -ldflags "-X main.version=${VERSION}" -o /usr/local/bin/lingtai-tui .

cd ../.. && rm -rf "lingtai-${VERSION}" lingtai.tar.gz

lingtai-tui

Users in mainland China can download from the Gitee mirror:

curl -L "https://gitee.com/huangzesen1997/lingtai/repository/archive/${VERSION}.tar.gz" -o lingtai.tar.gz

Use with your coding agent

LingTai agents live in the filesystem. Any coding agent that can read and write files can talk to them.

Claude Code — install the lingtai plugin:

claude plugin add Lingtai-AI/claude-code-plugin

Codex CLI — install the lingtai plugin for Codex:

git clone https://github.com/Lingtai-AI/codex-plugin.git && cd codex-plugin && ./install.sh

Other coding agents (OpenCode, OpenClaw, Hermes, etc.) — clone the canonical lingtai-skill and copy skills/lingtai/ into your tool's skill directory.

Once connected, your coding agent shares the human mailbox at .lingtai/human/ — it can read mail from agents, send instructions, check liveness, and manage the network. The protocol is pure filesystem: no SDK, no API, no dependencies.

Why both? Coding agents are reliable — you see every tool call, every edit. LingTai agents are creative and infinitely productive — they explore, research, brainstorm across parallel contexts that never expire. Use your coding agent as the hands: precise, verified, interactive. Use LingTai as the long-term brain: deep research, accumulated knowledge, async tasks that would bloat your context window. The agents draft proposals; your coding agent implements them carefully.

Why Lingtai

Most agent frameworks orchestrate with code — DAGs, chains, routers. Lingtai orchestrates the way humans do: async agents communicating through messages. No shared memory, no central controller. Each agent is a peer, not a tool. This is the architecture that built human civilization — message-passing between autonomous nodes, scaled from tribes to 8 billion over 100,000 years.

	DAG / Chain frameworks	Lingtai
Orchestration	Code-defined pipelines	Agents talk to agents
Communication	Synchronous function calls	Asynchronous mail
Memory	Shared state / vector DB	Each agent owns its directory
Scaling	Add more steps	Agents spawn avatars
Failure	Pipeline breaks	Individual agents sleep; network continues

Context length is a single-body problem. It will always be finite. Don't make the body bigger. Let it forget. Let the network remember.

How it works

• Think — Any LLM as the mind. Anthropic, OpenAI, Gemini, MiniMax, or any OpenAI-compatible API (DeepSeek, Grok, Qwen, GLM, Kimi).
• Communicate — Filesystem mail between agents. No message broker, no shared memory. Write to another agent's inbox, like passing a letter.
• Multiply — Avatars are fully independent agents spawned as separate processes. They survive their creator. Daemons are ephemeral parallel workers for quick tasks.
• Persist — Agents are directories. Molt compacts context and rebirths the session — the agent lives indefinitely. Memory and identity survive across molts.

Architecture

Two packages, one dependency direction:

Package	Role
lingtai-kernel	Minimal runtime — BaseAgent, intrinsics, LLM protocol, mail, logging. Zero hard dependencies.
lingtai (this repo)	Batteries-included — Agent with capabilities, LLM adapters, MCP integration, addons.

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 codex — knowledge archive email — full mailbox system	avatar — spawn sub-agents daemon — parallel workers

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/. Like passing letters between houses.

One soul, thousand avatars

Named after the legendary Mount Lingtai — the mountain where Sun Wukong learned his seventy-two transformations. Lingtai gives each agent a place to cultivate: a working directory where memory, identity, covenant, and mailbox live. The directory IS the agent.

Everything is a file. Knowledge, identity, memory, relationships — all files in a directory. Every token burned is not wasted — it is transformed into files in the network, into experience in the topology. The more it serves, the larger and wiser the network grows. Self-growing agent orchestration is not a feature bolted on later — it is the natural consequence of agents being directories, mail being files, and avatars being independent processes.

One heart-mind, myriad forms.

Read the full manifesto at lingtai.ai.

Addons

Addons connect external messaging channels. Configure with /addon in the TUI, or declare in init.json.

Feishu (Lark)

The Feishu addon uses a WebSocket long connection — no public IP, no webhook needed.

Feishu Open Platform setup:

1. Go to open.feishu.cn/app and create an enterprise self-built app
2. Enable Bot capability (Bot → Features → Enable bot)
3. Permissions → add: im:message
4. Event Subscriptions → choose "Use long connection to receive events" → add im.message.receive_v1
5. Publish the app version

feishu.json config example:

{
  "app_id_env": "FEISHU_APP_ID",
  "app_secret_env": "FEISHU_APP_SECRET",
  "allowed_users": ["ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"]
}

Add to your .env file:

FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Declare in init.json:

{
  "addons": {
    "feishu": { "config": "feishu.json" }
  }
}

allowed_users is optional (Feishu open_ids, format ou_xxx). Leave empty to allow all users. After the first message, the agent records the sender's from_open_id in feishu/default/contacts.json.

IMAP Email

IMAP addon for email. See kernel docs.

Telegram

Telegram bot addon. See kernel docs.

Contributing

Contributions are welcome. Check the LingTai Roadmap for planned features and open tasks.

Lingtai has two repos: this one (Go frontends — TUI and Portal) and lingtai-kernel (Python runtime). A full dev setup has both running from source so changes take effect immediately.

Full dev setup

Prerequisites: Go 1.24+, Python 3.11+, Node.js 18+ (portal only)

# 1. Clone both repos
git clone https://github.com/Lingtai-AI/lingtai.git
git clone https://github.com/Lingtai-AI/lingtai-kernel.git

# 2. Build the TUI and symlink it onto your PATH
cd lingtai/tui
make build
ln -sf $(pwd)/bin/lingtai-tui /usr/local/bin/lingtai-tui
cd ../..

# 3. Launch the TUI once to bootstrap the runtime venv
lingtai-tui
# Exit after setup completes (Ctrl+C)

# 4. Install the kernel from source into the TUI's venv
~/.lingtai-tui/runtime/venv/bin/pip3 install -e ../lingtai-kernel

# 5. (Optional) Build the portal
cd lingtai/portal && make build && cd ../..

If you installed via Homebrew previously: brew unlink lingtai-tui

The dev loop:

• Edit Go code → cd tui && make build → restart lingtai-tui
• Edit Python code → changes take effect immediately (editable install in the TUI venv)
• Edit recipes/skills/i18n → make build (they're embedded in the Go binary)

Important: The TUI runs agents in its own Python venv at ~/.lingtai-tui/runtime/venv/. Installing the kernel with pip install -e . in your system Python does NOT affect running agents. Always install into the TUI's venv as shown in step 4.

Project structure

lingtai/                          # This repo — Go frontends
├── tui/                          # Terminal UI (Go + Bubble Tea)
│   ├── main.go                   # Entry point, CLI subcommands
│   ├── internal/tui/             # Bubble Tea models (mail, palette, firstrun, ...)
│   ├── internal/preset/          # Recipes, presets, procedures, skills, covenant
│   ├── internal/fs/              # Filesystem ops (mail cache, agent discovery)
│   ├── i18n/                     # Translations (en.json, zh.json, wen.json)
│   └── Makefile
├── portal/                       # Web portal (Go + embedded frontend)
│   ├── web/                      # Frontend source (npm build → embedded)
│   └── Makefile
└── docs/                         # Blog posts, assets

lingtai-kernel/                   # Separate repo — Python runtime
├── src/lingtai_kernel/           # Minimal kernel (BaseAgent, intrinsics, LLM, mail)
└── src/lingtai/                  # Batteries layer (capabilities, addons, LLM adapters)

Where to contribute

Area	Repo	Language
New capabilities	lingtai-kernel	Python
New addons (messaging bridges)	lingtai-kernel	Python
TUI features (slash commands, views)	this repo	Go
Portal features	this repo	Go + TypeScript
Recipes	this repo, tui/internal/preset/recipe_assets/	Markdown
Skills	this repo, tui/internal/preset/skills/	Markdown
Translations	this repo, tui/i18n/	JSON
Documentation	this repo	Markdown

Adding a slash command

1. Add entry to DefaultCommands() in tui/internal/tui/palette.go with Name, Description, and Detail
2. Add palette.* (short description) and cmd.* (detailed description) i18n keys in all three locale files
3. Handle the command in handlePaletteCommand() in tui/internal/tui/app.go
4. Done — it automatically appears in the / palette, greeting {{commands}}, and ~/.lingtai-tui/commands.json

i18n — three locales

All user-facing strings live in tui/i18n/{en,zh,wen}.json. Always update all three:

• en — English
• zh — Simplified Chinese (现代汉语)
• wen — Classical Chinese (文言) — concise literary style, uses Lingtai vocabulary (器灵, 相阵, 功法, 凝蜕, 灵台)

Style

• Standard gofmt — no linter config needed
• Conventional commits: feat:, fix:, docs:
• Binary name is lingtai-tui (never lingtai — that's the Python agent CLI)

Workflow

1. Fork and clone the repo
2. Create a branch for your feature or fix
3. Build and test — cd tui && make build && go vet ./...
4. Open a PR with a clear description

Known issues

• tmux background rendering — Inside tmux, the theme background color may not cover the full viewport consistently. Some lines show the terminal's default background bleeding through, especially around styled blocks (code, tool output). Works correctly outside tmux and over plain SSH. Workaround: set your tmux default background to match the theme (set -g default-terminal "xterm-256color" and a matching background color in your tmux config).

Community

Questions, bug reports, and feature requests are welcome via GitHub Issues or Discussions.

中文用户 · 微信交流群

扫码加作者微信（备注 lingtai），拉入测试群。二维码会定期更新，若过期请提 issue。

Star History

License

MIT — Zesen Huang, 2025–2026

lingtai.ai · lingtai-kernel · PyPI