Architecture
Nested lingtai-dev-guide reference. Read this after the top-level router sends you here. This document maps the LingTai project: what the pieces are, how they connect, and where state lives.
The two repos
lingtai — Go monorepo (TUI + portal)
Location: github.com/Lingtai-AI/lingtai
Two binary targets in one repo:
| Binary | Source | Build output | Role |
|---|---|---|---|
lingtai-tui |
tui/ |
tui/bin/lingtai-tui |
Terminal UI — Bubble Tea v2 + lipgloss v2. Agent launcher, monitor, mail viewer, preset editor, first-run wizard. |
lingtai-portal |
portal/ |
portal/bin/lingtai-portal |
Web portal — Go HTTP server with embedded React 19 frontend. Network visualization, mail/replay UI, topology recorder. |
Key packages in tui/internal/:
| Package | Role |
|---|---|
tui/ |
Bubble Tea models for every screen (~22k LOC) |
preset/ |
Atomic {llm, capabilities} bundle layer |
migrate/ |
Retained historical/test migration registry (m001–m039); production startup no longer runs it or advances .lingtai/meta.json |
globalmigrate/ |
Live per-machine migrations under ~/.lingtai-tui/ (run by the TUI at startup) |
fs/ |
Filesystem read accessors into agent working directories |
config/ |
Global TUI config under ~/.lingtai-tui/ |
process/ |
Subprocess launcher for python -m lingtai run <dir> |
i18n/ |
en/zh/wen JSON tables (three locales always) |
Key packages in portal/internal/:
| Package | Role |
|---|---|
api/ |
HTTP server, handlers, replay endpoint |
fs/ |
Filesystem accessors (same shape as TUI's, portal-tailored) |
migrate/ |
Retained historical migration registry/tests (m001–m039); Portal production does not run it |
web/ |
React 19 + TypeScript + Vite frontend (embedded into Go binary) |
lingtai-kernel — Python kernel
Location: github.com/Lingtai-AI/lingtai-kernel
Published as the lingtai package on PyPI. Contains:
src/lingtai/kernel/— the minimal agent runtime (turn loop, lifecycle, tool dispatch, mailbox, molt orchestration)src/lingtai/— the batteries-included wrapper (MCP, FileIO, Vision, Search, CLI)
The wrapper depends on the kernel one-directionally. The kernel never imports from the wrapper.
How they connect
lingtai (Go) lingtai-kernel (Python)
┌──────────────┬───────────────┐ ┌────────────────────────┐
│ lingtai-tui │ lingtai-portal│ │ Agent runtime │
│ (terminal) │ (web) │◄──────►│ turn loop · tools · │
└──────────────┴───────────────┘ │ mailbox · molt │
filesystem only └────────────────────────┘
(.lingtai/<agent>/)
The TUI and portal never open a socket or RPC channel to a running agent. All
communication is through files — agent manifests, heartbeats, signal files,
mailbox folders, .notification/. This is a deliberate design choice: any new
cross-process communication should follow the same pattern (write a file, let the
other side poll).
TUI → kernel: The TUI launches agents via python -m lingtai run <dir> as a subprocess (tui/internal/process/launcher.go). After spawn, the TUI never talks to the agent process directly — only via the agent's working directory.
TUI → filesystem (read): .agent.json, .agent.heartbeat, mailbox/, logs/token_ledger.jsonl, history/chat_history.jsonl, system/*.md, .notification/*.json.
TUI → filesystem (write): Signal files only: .sleep, .suspend, .interrupt, .clear, .prompt, .refresh. Plus init.json via explicit user actions.
TUI ↔ Homebrew tap: Pushing a release tag runs the root release workflow, which updates Lingtai-AI/homebrew-lingtai/lingtai-tui.rb.
Portal ↔ TUI: The TUI discovers an installed lingtai-portal to launch on /viz; otherwise the binaries are independent.
Cross-repo dependencies
| Repo | Relationship to lingtai |
|---|---|
lingtai-kernel |
Runtime dependency only (the Python agent the TUI launches). Not a build-time dependency. |
lingtai-skill |
Canonical mailbox-protocol SKILL.md. Vendored into plugin repos. |
lingtai-claude-code |
Claude Code plugin (SessionStart hook, marketplace manifest). |
codex-plugin |
OpenAI Codex CLI plugin. |
lingtai-imap / lingtai-telegram / lingtai-feishu / lingtai-wechat |
MCP server addons. Each is a separate PyPI package. |
Lingtai-AI/homebrew-lingtai |
Homebrew tap for lingtai-tui. |
Where state lives
Per-project state: <project>/.lingtai/
.lingtai/
├── meta.json # legacy migration metadata (neither binary reads or advances it)
├── <agent>/
│ ├── init.json # agent's preset manifest
│ ├── .agent.json # written by agent, read by TUI/portal
│ ├── .agent.heartbeat # liveness signal
│ ├── .status.json # agent status
│ ├── mailbox/ # filesystem mailbox
│ │ ├── inbox/
│ │ ├── outbox/
│ │ ├── sent/
│ │ └── archive/
│ ├── .notification/ # notification producer files
│ │ ├── email.json
│ │ └── system.json
│ ├── logs/ # token ledger, events
│ ├── history/ # chat history, snapshots
│ ├── system/ # pad, summaries, config fragments
│ ├── .library/ # skill library
│ └── delegates/ # avatar ledger
├── human/ # user's pseudo-agent (no admin, no heartbeat)
├── .tui-asset/ # TUI-owned per-project caches
└── .portal/ # portal-owned files (port, recordings)
Per-machine state: ~/.lingtai-tui/
~/.lingtai-tui/
├── meta.json # live global migration version stamp (tui/internal/globalmigrate/)
├── tui_config.json # global TUI preferences
├── runtime/venv/ # Python venv with `lingtai` installed
├── presets/
│ ├── templates/ # TUI-owned, rewritten on Bootstrap
│ └── saved/ # user-owned, Bootstrap never touches
├── utilities/ # optional library paths for agents
└── ...