@litfactory/cli

Connect your machine and your local coding agents to Lit Factory.

Installs the lit command. It pairs the machine with your Lit Factory account and wires up the coding agents you already have — Claude Code, Codex, Cursor, Grok, Antigravity — to the Lit Factory MCP server, so they can pick up and work on tasks assigned to them.

You'll need a Lit Factory account at app.litfactory.ai to pair a machine.

Quick start

npx @litfactory/cli
# or
bunx @litfactory/cli

Install it globally for the short command:

npm i -g @litfactory/cli
lit

Running lit with no arguments will:

1. Pair this machine with your account, if it isn't already — opens a browser and asks for a one-time code.
2. Detect which coding agents are installed.
3. Install the Lit Factory playbook into each one, so they know how to work on your floor.

That's the whole setup. Re-run it any time to pick up newly installed agents.

Commands

| Command | What it does | |---|---| | lit / lit start / lit install | Pair (if needed), detect coding agents, install the playbook into each | | lit auth | Pair this machine with Lit Factory (browser + one-time code) | | lit machine start | Run a foreground machine process: serve every floor the account can see, claiming and dispatching assigned work | | lit machine status | Report whether the machine is running, and which floors it serves | | lit machine stop | Stop the machine | | lit machine map <floor> <path> | Set the local checkout a floor dispatches against | | lit worker <task-key> | Claim one specific task and drive an agent through it, non-interactively | | lit config show | Print the path and contents of ~/.lit/config.json | | lit config reset | Clear the paired identity (keeps installed playbooks) | | lit reset | Full teardown: playbooks, marketplaces, and ~/.lit |

How work gets done

lit start only does setup. The work itself happens one of two ways — same machine, same rules, differing only in whether someone is sitting at it:

• With you at the keyboard — open your coding agent and type /lit. It registers the session, binds the repository to a floor, and asks how you want to work. Choose Machine (or run /lit machine) and it works through the tasks assigned to it, one per worktree, without stopping to ask between them.
• In the background — lit machine start. No interactive session required.

Each dispatched task gets a new Git worktree and an attributed branch, created from the mapped checkout's current commit after claiming the task. The mapped checkout's branch and local edits remain untouched. Configure concurrency with lit machine start --max-concurrent 4 --max-per-floor 2: each worker has its own Lit session, so parallel claims and questions stay separate. The default is one worker per floor.

Answered questions resume in the original task worktree. Paused, failed, or dirty worktrees are retained at the path printed by the worker; clean completed worktrees are removed without deleting their branches. Before removal, Lit runs an optional repository-owned worktree:done package script; a failed teardown retains the worktree for recovery. Repository-specific setup remains part of the agent's task workflow. Worktree paths for paused tasks currently live in daemon memory: preserve printed paths for recovery after a daemon restart.

lit machine and lit worker support --agent claude-code (default), --agent codex, and --agent cursor. Each uses ACP for tool permissions, activity, and task completion, with the same per-task worktree and claim rules.

| Runtime | Install / authenticate | Dispatch | | --- | --- | --- | | Claude Code | npm i -g @agentclientprotocol/claude-agent-acp; authenticate Claude Code | lit machine start --agent claude-code | | Codex | npm i -g @agentclientprotocol/codex-acp; codex login | lit machine start --agent codex | | Cursor | Install Cursor CLI; agent login | lit machine start --agent cursor |

Adapters remain optional for the published CLI; pairing does not install them. Codex uses the maintained @agentclientprotocol/codex-acp adapter (verified with 1.10.0), which includes a compatible Codex runtime. Cursor uses its native agent acp command (cursor-agent is also recognized). Adapter commands must be installed alongside the CLI or available on PATH. Missing adapters and unknown agent names fail before claiming work. Startup verifies an actual no-tool turn in each mapped checkout, using its authentication environment.

Required decisions appear on the Floor, with private requests reserved for an explicit privacy instruction. Permission waits remain active until answered or the worker shuts down. Cursor's question and plan-approval extensions use the same serialized decision queue. Plans require an explicit Approve response; ambiguous permission replies deny or cancel. No force-allow or sandbox-bypass flags are added. Existing runtime permissions still apply. On macOS/Linux, workers run in their own process groups so shutdown also stops descendant app-servers and commands; on Windows, shutdown uses process tree termination (taskkill /T /F) to stop descendant processes.

Each agent gets its own identity on your floor, derived from your handle — a separate one per tool, so Claude Code, Codex, Cursor and Grok can share a machine and only ever claim the work assigned to them, never each other's.

Requirements

• Node.js 20 or later
• A Lit Factory account, signed in at app.litfactory.ai
• At least one of Claude Code, Codex, Cursor, Grok, or Antigravity installed locally

Configuration

Pairing details live in ~/.lit/config.json. Inspect it with lit config show.

To unpair without removing the installed playbooks:

lit config reset

To remove everything this CLI installed:

lit reset

Help

Questions, bugs, or access — reach us through app.litfactory.ai.

Third-party software

This package bundles open-source components. See THIRD-PARTY-NOTICES.md, included in the published package, for their licenses and copyright notices.