lingtai
CLAUDE.md510 starsChanged 3 months agoApache-2.0View on GitHub
Find and read this repository's local dev guide — the repository-root dev-guide-skill — before changing code, architecture documents, tests, or docs. It owns the workflow and routes each task through the exact baseline, the two distributed systems, focused validation, and the PR/side-effect gate without duplicating them: Read the dev guide first, then the paths it routes to, before editing. When a human gives conceptual, corrective, or ambiguous feedback — especially phrases like "stop and think," "you overcomplicated this," or corrections…
- Installs packages
- Commits and pushes
In this repositoryOne other file it gives its agents.
- lingtai-tui-devSkill
The file
We split this CLAUDE.md into the rules it gives an agent
8 rules. About 0 are common, 6 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Read the dev guide first, then the paths it routes to, before editing.
- Distinctive: line 16
When a human gives conceptual, corrective, or ambiguous feedback — especially phrases like "stop and think," "you overcomplicated this," or …
- Distinctive: line 22
Stop after stop: When a human says to stop coding, stop immediately.
- Distinctive: line 49
Treat repo cleanup as a small, evidence-backed change, not a bulk deletion pass.
- Very specific: line 64
All Python code (kernel runtime and batteries-included wrapper) now lives in the lingtai-kernel repo and is published as the lingtai …
- Distinctive: line 134
Verify dev mode is active:
- Distinctive: line 142
After a shared code change, rebuild BOTH binaries together.
- Very specific: line 197
When writing manifest.preset.* paths from Go code, always use preset.RefFor(p) — it picks the right subdirectory based on Source instead of …
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Before any development work
Find and read this repository's local dev guide — the repository-root dev-guide-skill — before changing code, architecture documents, tests, or docs. It owns the workflow and routes each task through the exact baseline, the two distributed systems, focused validation, and the PR/side-effect gate without duplicating them:
- Where is the code and how is it connected? The distributed code-navigation system, rooted at
ANATOMY.md(descend intotui/ANATOMY.md/portal/ANATOMY.md). - What do interfaces and expected agent behavior promise? The distributed interface/Behavior system, rooted at
CONTRACT.md.
Read the dev guide first, then the paths it routes to, before editing.
Clarify human intent before coding
When a human gives conceptual, corrective, or ambiguous feedback — especially phrases like "stop and think," "you overcomplicated this," or corrections that map to multiple implementations:
- Pause coding. Restate the intended contract and wait for confirmation when scope is ambiguous.
- Classify findings. Label each concern: confirmed defect, edge risk, future refactor, or documentation/process issue. Do not treat all concerns as immediate code changes.
- Name the smallest change. Identify the minimal fix. Do not expand into a broader refactor because nearby code is related.
- No direct edits for self-initiated improvements. Self-initiated code changes go through issue → branch → PR → merge. Direct edits are for explicitly requested emergency fixes only. (The "Always work in a worktree" section below carves out single-line fixes and doc tweaks — those exceptions still apply.)
- Stop after stop. When a human says to stop coding, stop immediately. Switch to clarification or reporting only.
Always work in a worktree, never directly in the main checkout
For any non-trivial change (anything beyond a single-line typo fix), create a git worktree first and do the work there. Both this TUI repo and its sibling kernel repo see concurrent branches and stashed WIPs; editing the main checkout has repeatedly led to branch switches reverting in-flight edits, mixed-author dirty trees getting committed together, and lost work from parallel-session resets.
Convention: .worktrees/<slug>/ on a fresh branch off origin/main.
cd ~/Documents/GitHub/lingtai
git fetch origin main
git worktree add -b <branch-slug> .worktrees/<slug> origin/main
cd .worktrees/<slug>
# ... edit, build, commit, push ...Cleanup when done:
git worktree remove .worktrees/<slug>
git branch -d <branch-slug>Hard rule: if a change touches more than ~10 lines or spans more than one file, move it to a worktree before editing. Single-line fixes and doc tweaks can stay in the main checkout. The 30 seconds to spin up a worktree are recouped the first time a parallel session resets the branch out from under you.
Repository hygiene: reports, discussions, and scratch output
Treat repo cleanup as a small, evidence-backed change, not a bulk deletion pass. This repo intentionally keeps some human-facing artifacts in git history:
- Routine PR explainers are local-only output, not repo artifacts. Write them under ignored
artifacts/, ignoredreports/,tmp/, or an agent/worktree report workspace and hand the human the absolute path. Commit report HTML only when it is deliberate long-term/release documentation, explicitly requested by the human, or intentionally linked by repo docs; usegit add -ffor that exception and explain why in the PR. discussions/contains agent-filed patch specs and design notes. Do not remove or rewrite them during generic cleanup; close or archive them only through an owner-approved, issue-specific decision.prompt/archive/contains historical prompt material. Treat it as manual-review territory unless a reference check and owner approval say otherwise.- Local scratch directories (
tmp/,artifacts/,.worktrees/, build bins, caches) should be ignored rather than committed. If a cleanup proposal touches durable docs/reports/discussions, split that into a separate owner-gated PR.
What is 灵台
灵台 (Língtái) is a generic agent framework — an "agent operating system" providing the minimal kernel for AI agents: thinking (LLM), perceiving (vision, search), acting (file I/O), and communicating (inter-agent email). Domain tools, coordination, and orchestration are plugged in from outside via MCP-compatible interfaces.
Named after 灵台方寸山 — where 孙悟空 learned his 72 transformations. Each agent (器灵) can spawn avatars (分身) that venture into 三千世界 and return with experiences. The self-growing network of avatars IS the agent itself — memory becomes infinite through multiplication.
Repository Scope
All Python code (kernel runtime and batteries-included wrapper) now lives in the lingtai-kernel repo and is published as the lingtai package on PyPI. This repo contains the Go TUI and the retained, deprecated Portal codebase.
tui/— Terminal UI (Go + Bubble Tea). Launches and monitors agents from the command line. Builds totui/bin/lingtai-tui.portal/— Retained, deprecated web portal (Go + embedded web frontend). It remains separately buildable for repository development and builds toportal/bin/lingtai-portal; the installers, release workflow, and Homebrew do not build or install it.
Neither binary has a direct Python dependency. Both communicate with Python agents exclusively through the filesystem (.lingtai/ directory, heartbeat files, signal files). Agents are launched by the TUI via python -m lingtai run <dir> as a subprocess.
Sibling repos (not in this directory)
Other LingTai components live as sibling repos under ~/Documents/GitHub/:
lingtai-kernel/— Python kernel +lingtaiPyPI package (agent runtime, LLM interface, mailbox core, preset schema validation).lingtai-skill/— Canonical mailbox-protocol skill. Single source of truth forskills/lingtai/SKILL.md(the filesystem mailbox protocol). Plugin repos vendor it vialingtai-claude-code/scripts/sync-from-canonical.sh— edit here, sync there.lingtai-claude-code/— Claude Code plugin (claude plugin add Lingtai-AI/claude-code-plugin). Owns the SessionStart hook and the Claude marketplace manifest. The plugin cache at~/.claude/plugins/cache/lingtai/gets overwritten on update — don't edit that.codex-plugin/— OpenAI Codex CLI plugin (./install.shcopies into~/.codex/skills/lingtai/and~/.codex/hooks.json).- MCP addon repos — sibling MCP servers wired in via the kernel's
mcpcapability. Each is a thin adapter exposing one external system as a tool surface plus a LICC inbox listener:lingtai-imap/— Gmail/IMAP maillingtai-telegram/— Telegram bot APIlingtai-feishu/— Feishu/Lark messaginglingtai-wechat/— WeChat (gewechat) messaging
lingtai-fangcun/— standalone skill/tool component.lingtai-agora/,lingtai-web/— distribution and web surfaces.lingtai-ad/— launch/marketing materials.
Build
# Build the TUI
cd tui && make build
# Output: tui/bin/lingtai-tui
# Build the portal (builds embedded web frontend first)
cd portal && make build
# Output: portal/bin/lingtai-portalCross-compilation targets (darwin/linux/windows, amd64/arm64) are available via make cross-compile in each directory.
Releases
See RELEASING.md for the full process. Key points:
- Tag and push:
git tag v0.X.Y && git push origin v0.X.Y - The root
.github/workflows/release.ymlworkflow validates the tag, peels it to a commit SHA, and publishes the deterministic TUI source archive plus checksum; it also relays source-only asset metadata tolingtai-web update-homebrewconsumes that producer-owned source archive and writes a TUI-only source-build formula (there is no Portal or Windows bundle release job)- Edit the Homebrew tap manually only as a fallback/debug step if the workflow failed or could not run
Projects
TUI (tui/)
Go + Bubble Tea terminal interface. Key facts:
- Binary name:
lingtai-tui(neverlingtai-agent— that is the Python agent CLI) - Launches agents via
python -m lingtai run <dir>subprocess - Communicates with running agents via filesystem only: reads
.lingtai/metadata, heartbeat files, and signal files inside each agent working directory - Agent discovery uses
lingtai.kernel.handshakeconventions (is_agent,is_alivechecks on working directories)
Dev mode for the TUI/portal binaries
Dev mode means /opt/homebrew/bin/lingtai-{tui,portal} are symlinks to the freshly-built binaries in this repo, so which lingtai-tui resolves to ~/Documents/GitHub/lingtai/tui/bin/lingtai-tui. Once the symlinks are in place, every make build here is immediately picked up by the user's shell — no brew reinstall cycle.
Setup (one-time, only needed if the symlinks don't already exist):
ln -sf ~/Documents/GitHub/lingtai/tui/bin/lingtai-tui /opt/homebrew/bin/lingtai-tui
ln -sf ~/Documents/GitHub/lingtai/portal/bin/lingtai-portal /opt/homebrew/bin/lingtai-portalTo go back to the brew-installed pair: brew reinstall lingtai-tui overwrites the symlinks with real binaries.
Verify dev mode is active:
readlink -f $(which lingtai-tui) # → ~/Documents/GitHub/lingtai/tui/bin/lingtai-tui
lingtai-tui --version # → vX.Y.Z-N-gSHORTSHA (git describe — never a clean vX.Y.Z tag in dev)A clean vX.Y.Z version string means the brew-installed binary is in front; a -N-gSHORTSHA suffix means dev mode is live. The -N-g… form comes from git describe --tags and is what make build bakes into -X main.version.
After a shared code change, rebuild BOTH binaries together; the retained project migration registry is not a runtime compatibility gate.
Migrations (tui/internal/migrate/)
This package is retained historical Git source and direct unit-test coverage for
m001–m039. Production TUI startup, project creation, launcher, and diagnostics
do not import or execute it, stamp .lingtai/meta.json, or maintain a project
migration-progress/version chain. Existing project files continue as stored; the
kernel reader/Nudge and explicit Agent edits own compatibility repair. Keep the
registry/API at CurrentVersion = 39 only for historical tests/parity. Do not add
a new production migration, version check, stamp, preflight, or automatic
init.json rewrite.
The retained m001–m039 implementation and tests must not be deleted. The six
retired m040/preflight paths are the only authorized deletions in the v4.2 recut.
The adjacent migration/migration.md is prose/Git history, not runtime state.
Dev-mode rebuild: rebuild both binaries after ordinary code changes as usual:
cd ~/Documents/GitHub/lingtai/tui && make build
cd ~/Documents/GitHub/lingtai/portal && make buildThis is no longer a migration-version compatibility gate.
Recent historical entries worth knowing about:
- m029 —
manifest.preset.path(directory the kernel scanned) →manifest.preset.allowed(explicit list of allowed preset path strings). - m030 — preset directory split: rewrites flat
~/.lingtai-tui/presets/X.jsonpaths in init.json to eitherpresets/templates/X.jsonorpresets/saved/X.json.
Global migrations (tui/internal/globalmigrate/)
Per-machine analogue of tui/internal/migrate/. Same conventions (versioned, append-only, forward-only, m<NNN>_<name>.go files registered in globalmigrate.go), but scoped to global state under ~/.lingtai-tui/. Version tracked in ~/.lingtai-tui/meta.json. Use this for cleanup that affects the whole machine rather than a single project — e.g. Homebrew tap rename, tui_config.json schema bumps, runtime dir relocation. Failures are best-effort: they go to stderr and don't abort startup. Run from main.go via globalmigrate.Run(globalDir). Note: v2 (split-presets-dir, formerly m002) is a neutralized no-op tombstone — its destructive preset-moving body caused the preset-loss incident and was removed; the version entry is retained inline for advancement semantics. Migrations that move or delete user files must refuse to overwrite/delete on collision.
Preset architecture (tui/internal/preset/)
Presets are atomic {llm, capabilities} bundles agents can swap into at runtime. The on-disk layout under ~/.lingtai-tui/presets/:
templates/— TUI-owned.RefreshTemplates()rewrites this directory wholesale on every Bootstrap from embedded data, prunes retired entries. Users should never edit files here directly; an upgrade will erase their changes.saved/— user-owned.Save()always writes here; Bootstrap never touches it. The wizard's auto-clone-on-edit lands new presets here as<template>-<N>.json.
The directory IS the answer to "is this a template?" — there's no in-band marker. Each loaded Preset carries a Source field (SourceTemplate / SourceSaved) set by List() / Load(). Prefer IsTemplate(p) over the legacy IsBuiltin(p.Name) for any loaded preset; the latter still exists for callers that only have a name.
manifest.preset schema in init.json:
"preset": {
"default": "~/.lingtai-tui/presets/templates/minimax.json",
"active": "~/.lingtai-tui/presets/templates/minimax.json",
"allowed": [
"~/.lingtai-tui/presets/templates/minimax.json",
"~/.lingtai-tui/presets/saved/zhipu-1.json"
]
}Authorization is declared in allowed — the kernel refuses runtime swap to anything not in that list (system.py:_refresh allowed-gate). Path normalization in the gate uses _preset_ref_in so ~/-prefixed and absolute forms compare equal. default and active MUST both appear in allowed; init_schema.validate_init enforces this.
When writing manifest.preset.* paths from Go code, always use preset.RefFor(p) — it picks the right subdirectory based on Source instead of hardcoding presets/.
Portal (portal/, deprecated)
Go server with an embedded web frontend. Key facts:
- Binary name:
lingtai-portal - Web assets are built with
npm run buildinsideportal/web/and embedded into the Go binary at compile time viaembed.go - Communicates with agents via filesystem only (same conventions as TUI)
make buildruns the full pipeline: web deps → web build → go build
TUI patterns and gotchas
These are concrete patterns that have caused regressions when missed. Treat each as a checklist item before commits in the relevant area.
Bubble Tea v2: paste delivery
Bubbletea v2 delivers terminal events as separate message types: tea.KeyPressMsg for individual keypresses, tea.PasteMsg for clipboard blobs from bracketed-paste mode, tea.MouseMsg, etc. Any Update dispatcher that handles case tea.KeyPressMsg: (or v1's tea.KeyMsg) needs a fall-through that forwards remaining message types to whichever text widget is focused. Otherwise paste silently drops.
For embedded sub-models (e.g. PresetEditorModel hosted inside FirstRunModel), the host's outer dispatcher must forward paste msgs into the sub-model. If the host's default: branch enumerates focused widgets per-step but misses the step that hosts an embedded model, paste dies before reaching the sub-model — and adding a fall-through inside the sub-model's own Update is useless because the msg never arrives. Trace top-down (tea.Program → host's outer switch → sub-model's outer switch → widget) and ensure every layer either handles or forwards tea.PasteMsg.
Symptom of a missed forwarder: typing into an input works, pasting does nothing.
Bubble Tea v2: textarea vs textinput
textinput is single-line and drops characters on multi-byte / clipboard pastes. textarea is the multi-line cousin that handles paste cleanly via its pasteCmd path. For any paste-friendly field (API keys, base URLs, anything the user might paste from a browser), use textarea even when the content is conceptually one line:
ta := textarea.New()
ta.CharLimit = 512
ta.SetWidth(50)
ta.SetHeight(1)
ta.ShowLineNumbers = false
ta.Prompt = ""
ta.KeyMap.InsertNewline.SetKeys() // single-line: no newline insertion
ta.SetStyles(themedTextareaStyles())themedTextareaStyles() is in the tui package — always apply it. A bare textarea.New() ships dark default cursor/focus colors that render as a black smear against the warm LingTai theme. Before adding any new textarea.New instance, grep the package for existing instances and copy their style + keymap setup.
i18n: three locales always
Adding a new i18n key means updating all three of tui/i18n/en.json, tui/i18n/zh.json, tui/i18n/wen.json. Missing translations show as the raw key (firstrun.preset_cfg.hint) on screen — they don't fall back. If a key is genuinely English-only (procedural notes, error stacks), document why; otherwise translate.
TUI binary
The TUI binary is lingtai-tui, never lingtai-agent. lingtai-agent is the Python agent CLI (installed by the kernel into the TUI's runtime venv at ~/.lingtai-tui/runtime/venv/bin/lingtai-agent). Build the TUI to tui/bin/lingtai-tui; never to tui/bin/lingtai-agent.
Agent venv
Agents run inside the TUI's runtime venv at ~/.lingtai-tui/runtime/venv/. When making kernel changes (lingtai-kernel/src/lingtai/...), the editable install in this venv picks them up automatically — no reinstall needed. To verify, ~/.lingtai-tui/runtime/venv/bin/python -c "import lingtai; print(lingtai.__file__)" should resolve to the kernel source tree, not site-packages.
Auto-upgrader respects editable installs (as of b074969). tui/main.go:283 still calls config.CheckUpgrade on every TUI launch, but UpgradePythonRuntime now probes PEP 610's direct_url.json first (tui/internal/config/venv.go:isEditableLingtaiInstall). When dir_info.editable == true, it logs "Python lingtai is an editable install … skipping upgrade" and returns before touching PyPI or running pip. The doctor force=true path honors the same gate — a forced repair won't nuke a dev setup either. So once you have an editable install, it stays.
To establish dev mode in the first place (or recover from a pre-fix clobber):
~/.local/bin/uv pip install -e ~/Documents/GitHub/lingtai-kernel \
-p ~/.lingtai-tui/runtime/venv(use uv, not pip — the venv is uv-managed and has no pip symlink, only pip3). Verify with the import-path check above; the path should resolve to ~/Documents/GitHub/lingtai-kernel/src/lingtai/__init__.py, not under site-packages/.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

