| name | dev-guide-architecture |
| description | Nested lingtai-dev-guide reference for the project architecture: Go TUI/portal monorepo, Python kernel, MCP addon repos, filesystem IPC, and where per-project/per-machine state lives.
|
| version | 1.0.0 |
| last_changed_at | 2026-07-18T00:00:00Z |
| maintenance | If you find stale or incorrect information here, use the lingtai-issue-report skill to assemble evidence and obtain per-issue human consent before filing an issue. Never include secrets, credentials, tokens, or private paths. |
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/ | Versioned, append-only migration system for .lingtai/ state |
globalmigrate/ | Per-machine migrations under ~/.lingtai-tui/ |
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/ | Versioned migrations (shares meta.json version space with TUI) |
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, soul/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 · soul · 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, .inquiry, .forget. 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 # migration version stamp (shared TUI + portal)
├── <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
│ │ ├── soul.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 # global migration version stamp
├── 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
└── ...
