Terminal CLI

The lime binary is the canonical Lime experience. It hosts the agent loop, drives the streaming TUI, exposes a JSON-RPC bridge, and serves as the host for every other surface (VS Code, web PWA, remote control).

When to reach for the CLI

• Day-to-day coding sessions. Run lime in a project and chat with the agent in your terminal.
• CI / scripts. Use lime --resume <ref> /<cmd> for non-interactive slash commands and lime status / lime sandbox for snapshots.
• Self-hosting the bridge. lime bridge --ws … makes Lime drivable by your own client.
• MCP server administration. lime mcp add|list|enable|disable|... is the lowest-friction surface for managing servers.

See Non-interactive use for the full set of non-interactive entrypoints.

The IDE companion

Even when you primarily live in the terminal, the IDE companion is worth running. It is a per-window WebSocket server, lockfile-discovered by the lime CLI under ~/.lime/ide/. When detected, the CLI delegates:

• Diff review (the TUI shows you a synced diff in VS Code).
• Selection access (@selection in your prompt picks up the editor’s selection).
• Diagnostics (the agent can read your editor’s “problems” panel).

The companion is opt-in per IDE window and gated by --ide:

--ide value	Behavior
auto (default)	Discover an IDE companion via the lockfile.
off	Disable IDE companion features.
<port>	Connect to an explicit port instead of using the lockfile.

Output streams

By default, Lime writes:

• The streaming TUI to the controlling terminal.
• Audit and diagnostic events to ~/.lime/logs/<session-id>.jsonl.
• The session log itself to .lime/sessions/<session-id>.jsonl (or ~/.lime/sessions/... for global sessions).

lime is not currently designed to be redirected — for piping, use the bridge.

Process model

Each lime invocation is a single process that:

• Owns the agent loop.
• Manages worker processes for sub-agents (with their own scratchpads).
• Spawns transport processes for stdio MCP servers.
• Optionally manages a cloudflared child for lime remote start.

When you Ctrl-C the parent, every child is reaped and pending sessions are flushed to disk. Recovery on next launch is automatic — no orphaned state is left behind.