Main agent
The one resident agent you talk to.
Created at first launch, it is the persistent hub: it holds the plan and memory, and it spawns the others. Use it for anything small — most of the time this is all you need.
Beginner Tutorial
From zero to your first task
LingTai gives you a long-lived AI assistant that lives inside a project folder on your own machine. This guide takes you from installing it to handing it a real first task — and explains just enough of how it thinks to keep going on your own.
~10 minute read
What LingTai is — and is not
LingTai is a home for a persistent AI agent that you run yourself. It works inside a project directory and keeps everything it knows — memory, identity, knowledge, skills — as plain files in that directory. The guiding idea: the agent is its files, and the files are the agent. Swap the underlying model and the agent remains.
It is
- A local, file-based home for an AI assistant you own and grow over time.
- A terminal app (a TUI) you drive with plain language and a few slash commands.
- A place where memory, identity, knowledge, and skills are just files in a folder.
It is not
- A chatbot website or a hosted service — it runs on your machine, in your project.
- Tied to one model — it is model-agnostic; the LLM is swappable.
- Only for coding — the agent can take on any task you can describe and supervise.
Prerequisites and install
Before you start
- A Unix-like terminal — macOS or Linux (Windows works through WSL). A dark terminal theme looks best.
- Python 3.11 or newer. In practice LingTai provisions and manages its own runtime for you, so you rarely touch Python directly.
- At least one LLM provider credential (an API key). You enter it during first-run setup; no LingTai account is required.
Install (recommended)
This is the primary install path for new users. It fetches a prebuilt release, sets up the managed runtime, and needs no Homebrew.
$ curl -fsSL https://lingtai.ai/install.sh | bash
Other ways to install
Homebrew (existing users)
brew install lingtai-ai/lingtai/lingtai-tui Still supported during the migration period. If you already installed with Homebrew, upgrade with: brew update && brew upgrade lingtai-ai/lingtai/lingtai-tui — then restart the TUI.
pip (development / diagnostics only)
pip install lingtai Not a normal install or upgrade path. Reach for pip only when you are developing or diagnosing the kernel itself — it does not manage a project runtime.
Keeping it up to date
With the recommended install, the TUI manages its own runtime updates. Remember there are two layers — the TUI program and the managed Python runtime; if a version looks stale after an upgrade, restart the TUI and run /doctor to repair the runtime.
First launch and your first project
A LingTai project is just a folder. You launch the TUI inside it, and everything the agent creates lives there. On the very first run, a short wizard walks you through setup and starts one resident agent.
-
Make a project folder and enter it
The folder you are in becomes the project. Start with an empty one while you learn.
$mkdir my-project && cd my-project -
Launch the TUI
This opens LingTai in the current directory. The first run auto-creates a .lingtai/ folder and provisions the runtime.
$lingtai-tui -
Follow the setup wizard, then pick the Tutorial recipe
The wizard asks for your API key, a model, an agent name, and a starting recipe. Choose the built-in "Tutorial" recipe: the agent then teaches you the system, lesson by lesson, right inside the TUI.
That first wizard is the /setup flow. You can re-run /setup any time to change your provider, model, or capabilities; add /setup credentials to jump straight to the credential check.
Your first real task
You talk to the agent by typing plain messages and pressing Enter. A good first task is safe, concrete, and read-only — let the agent look before it touches anything.
Try typing something like
Help me get oriented in this project. First read the README and the docs folder — do not change any files. Then tell me what the project is for, which files matter most, and what you would suggest doing next.
How to give instructions the agent can act on
- State the goal — what "done" looks like, in one sentence.
- Set the scope — which files or folders it should (and should not) touch.
- Name the safety limits — e.g. do not send messages, delete files, or expose secrets.
- Say how to report back — a summary, a list, a file, whatever you want.
Seeing what the agent is doing
There is no /status command. Instead, open a dashboard. The most useful is /kanban, which shows each agent's status, heartbeat, token usage, and how full its context window is.
/kanban | The network dashboard: per-agent status, heartbeat, token/stamina, and context usage. |
/daemons | Inspect the short-lived worker runs an agent has spawned — their task, trace, and status. |
lingtai-tui list --detailed <project-dir> | From a shell: list every agent in a project directory (the main agent is marked). |
The cast: main agent, daemon, avatar
LingTai is not one agent but a small organization. Three roles are worth knowing early; a rule of thumb follows each.
Daemon
A short-lived parallel worker.
Emanated for a noisy, bounded job — bulk lookups, cross-checking, a wide scan — then discarded. You keep its conclusions, not the worker. Use one for a one-off burst of parallel work.
Avatar
A persistent, specialized teammate.
A long-lived agent with its own memory, mailbox, and responsibility — like a fixed teammate who owns one domain. Create one when a specialty deserves to persist across many sessions.
How an agent remembers: files, Knowledge, Skills
Everything the agent knows lives on disk under .lingtai/, which you can inspect with ordinary tools like ls and cat. Three tiers are worth telling apart.
Files
Ordinary working files.
The reports, edits, and artifacts the agent reads and writes anywhere in your project. Nothing special — just the work itself.
Knowledge
Durable, private, per-agent memory.
Lasting facts, paths, decisions, and lessons an agent keeps for itself, in its knowledge/ folder. Only a short index sits in the prompt; full entries are read on demand. Browse it with /knowledge.
Skills
Reusable playbooks, shared by all agents.
Markdown playbooks (each a SKILL.md) that describe how to do a recurring task, loaded on demand. Unlike Knowledge, Skills are shared across every agent in the same .lingtai/. Browse them with /skills.
Context and molt
An agent can only hold so much conversation in view at once — its context window. Think of it as a desk that slowly fills with paper. When it gets full, the agent molts: it writes itself a careful summary, then clears the window and carries that summary — plus all its durable memory — forward onto a clean desk.
This is normal housekeeping, not a failure. Under context pressure the agent will molt on its own, after a short series of warnings. You usually do not need to do anything.
If a task matters, you can prepare for a molt: ask the agent to "wrap up and summarize" first — saving the goal, what is done and not done, key file paths, conclusions, and next steps into its memory — and then run /molt to force it. (Do not confuse this with /clear, which wipes the conversation without saving, or /nirvana, which irreversibly erases the whole agent.)
Optional: external channels and add-ons
By default you talk to your assistant in the terminal. If you want, you can also reach the same assistant — same memory, same history — through outside channels. These are optional add-ons, configured with /mcp.
- Telegram Talk to your assistant from Telegram, with an optional allowlist.
- Feishu / Lark Connect over a long-lived WebSocket — no public IP or webhook needed.
- WeChat / WhatsApp Reach the assistant through a curated bridge for each messenger.
- Email (IMAP) Give the assistant a real inbox over IMAP/SMTP, with safe defaults for unknown senders.
After changing any channel or MCP configuration, run /refresh so the agent picks it up.
Command and shortcut reference
Type / in the TUI to open the command palette; it fuzzy-matches, so /skl finds skills. A compact set to get started:
Common commands
/setup | Set up or change your provider, model, capabilities, and credentials. |
/kanban | The network dashboard, including context-window usage. |
/skills | Browse the shared skill playbooks. |
/knowledge | Browse this agent's private knowledge (aliases: /library, /codex). |
/mcp | Manage external channels and other MCP add-ons. |
/molt | Save context, then reset the conversation window. |
/doctor | Diagnose connectivity, keys, models, and repair the runtime. |
/help | Open the in-TUI help reader for the full list. |
Keyboard shortcuts
| Enter | Send the current message. |
| Shift+Enter / Ctrl+J | Insert a newline instead of sending. |
| / | Open the command palette (type to fuzzy-filter). |
| Ctrl+E | Open an external editor for a long message. |
| Ctrl+T | Switch between agents inside the /skills, /knowledge, and /system views. |
Troubleshooting
- lingtai-tui: command not found
- The install directory is not on your PATH. Open a new terminal, or add the install location (shown at the end of the installer output) to your PATH, then try again.
- The TUI opens but the assistant does not respond
- It may be running a long tool or molting — give it a moment. Then check /kanban, run /doctor, and look at the tail of .lingtai/<agent>/logs/agent.log.
- I upgraded but nothing changed
- Remember the two layers — the TUI program and its managed Python runtime. Restart the TUI; if a version still looks stale, run /doctor to repair the runtime.
- A skill or command seems to be missing
- Run /doctor to re-extract the bundled skills and utilities, and check that the right preset is active.
Next steps
The fastest way to go deeper is inside the product itself: launch lingtai-tui, pick the Tutorial recipe, and let the agent teach you concept by concept. When you want more, these are the canonical sources.