---
name: lingtai-ai/dev-guide-architecture
source: https://app.decimal.ai/s/lingtai-ai-dev-guide-architecture@2/SKILL.md
source_sha256: d99f4c6e2aa4
---

# 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, 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`. 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
│   │   ├── 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                    # 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
└── ...
```