How Lanchu works

What it solves, what you do, and how to see, update, and uninstall it.

What it solves

When you run several AI agents at once, they step on each other's work, act blindly, and there's no way to see or trust what they did.

Lanchu is a local-first control & trust layer. It gives your agents a shared workspace so they coordinate without colliding, keeps each one in its lane (a role can only touch what it's allowed to), and gives you a panel + full history to see and trust everything they do. It doesn't run or orchestrate your agents — it coordinates and bounds the work. Nothing ever leaves your machine.

What you do as a user

Start it in your project — a guided wizard sets up your organization, agent and role:
```
npx lanchu
```

Connect your agent (Claude Code). The wizard wires it for you, or run the printed command, e.g.:

claude mcp add lanchu --transport http http://127.0.0.1:4319/mcp \
  --header "Authorization: Bearer <token>"

Tell your agent to work in Lanchu. It reads its objective, role and tasks, claims what's in its lane, and reports progress — all visible to you. Run more agents (with different roles) and they coordinate through Lanchu, never directly.

Two roles in practice: an operator (semi-technical) does the setup; a supervisor just watches the panel — no coding needed.

How to see things

Command	Shows
`lanchu panel`	Opens the live dashboard: agents, tasks, roles, docs, and the audit log.
`lanchu agents`	Who's active, their role and what they're on.
`lanchu tasks`	The task board (flags stale tasks).
`lanchu stats`	A quick local summary.
`lanchu doctor`	Environment + version check.

The panel is at http://127.0.0.1:4319 and updates live. It's local and read-focused; the supervisor actions (retire an agent, release/reassign a task) are there too.

See it inside Claude

Run lanchu statusline once to wire a status line into Claude Code — then every session shows, at the bottom, whether Lanchu is running and the team's pulse:

lanchu ● acme/web · 3 agents active · 5 open tasks

Your agent also greets you on connect (its name, role and task count), so you know Lanchu is live without leaving the chat.

For one-word control from inside Claude Code, install the slash command once:

npx lanchu install-commands

Then type /lanchu panel, /lanchu status, /lanchu spawn "write the docs" or /lanchu tile — these are your controls (opening the panel, spawning a teammate, arranging terminals), separate from what the agent does.

How to update

Using npx (the usual way): npx lanchu@latest always runs the newest version — nothing to update.
Installed globally: npm i -g lanchu@latest.
Check anytime: lanchu upgrade tells you if a newer version exists.
Optional notice: lanchu notify on shows a one-line heads-up when an update is available (off by default; only reads the public npm registry).

How to uninstall

lanchu uninstall           # stops the server, shows where your data lives
lanchu uninstall --purge   # also deletes all local Lanchu data

To clean up fully:

claude mcp remove lanchu — remove the MCP client entry.
rm -rf .lanchu — the per-project config, in each project.
npm rm -g lanchu — only if you installed it globally (npx needs no removal).

Your data (orgs, agents, tasks, docs, audit) is a single local database under your OS app-data folder — removing it with --purge leaves no trace.