Agents / Claude Code

Claude Code

The lwis plugin delivers your captures into the Claude Code sessions you choose. It ships inside the lwis binary, stays inert until you attach a session, and never relays tool approvals from a device.

Set up the plugin

lwis setup claude                # install the plugin for every project, start lwisd once
lwis install-service --enable    # keep lwisd running across logins
lwis pair --label laptop         # pair your phone or browser, if you haven't yet

lwis setup claude writes the plugin as a local marketplace (lwis-local) under ~/.local/share/lwis/claude and installs lwis@lwis-local at user scope. Its hooks and MCP server call this lwis binary by absolute path with the daemon's runtime directory, so PATH and XDG_RUNTIME_DIR don't matter inside Claude Code.

Plugins load when a session starts. Exit sessions that were already running, then claude --continue reopens the same conversation.

The hooks never start lwisd. If the daemon isn't running, the plugin's tools answer "lwisd not running" and the hooks stay silent. Run it as a service, or by hand with lwis up (lwis up --idle-exit 60 exits after an hour with nothing attached).

After an update, the next session start asks a running lwisd to re-exec itself from the updated binary (only the same file, only a newer version; logged in lwis log).

Attach a session

A new session is not reachable: your devices don't list it, and captures addressed to it are refused. Once per project, the session start shows "lwis: this session isn't attached; /lwis:on to receive captures".

An explicit /lwis:on or /lwis:off is remembered per Claude session for 30 days (it follows /clear and /resume), and an explicit detach beats the allowlist. lwis sessions lists every session lwisd knows, attached or not.

The slash commands carry disable-model-invocation, so Claude doesn't run them by itself. An agent allowed to run shell commands without asking could still run lwis directly: your permission prompts are that gate.

How captures reach a session

lwisd picks a delivery path ("rung") per capture and per attached session. lwis doctor shows which one each session is on, and why.

• Without --wake, a capture never starts a turn: it waits for your next prompt and a desktop notification tells you it's there (where notify-send or osascript and a display are available). The exception is lwis setup claude --channels: with channels preferred, R0 delivers to every attached session.
• Claude Code labels an inbox message as coming from another process. A session that bypasses permission prompts holds it for your approval, and crossSessionInbound: "hold" in your Claude settings does the same. A held message counts as delivered: lwisd never steps around a hold.
• crossSessionInbound: "refuse" turns R1 off: lwisd tries the channel (if your organisation enables channels), with R2 and R3 as backup.
• Team and Enterprise organisations have to enable channels (channelsEnabled: true in managed settings). Without that, Claude Code logs Channel notifications skipped: channels not enabled by org policy.

Inside Claude, the plugin provides four tools: lwis_get_capture (view a capture's images, gestures and page targets), lwis_list_captures (captures still available to this session, for up to 24 hours or until the session ends), lwis_reply (a plain-text reply to the device, at most 1000 characters; to an agent pairing's report, up to 8000 and one file) and lwis_request_capture (ask you to take a capture on a paired device).

Held captures and strict mode

Some sessions only get a stub instead of the capture. Claude can view it after you accept it:

/lwis:accept c_…

Captures are held when:

• the session's permission mode approves tools by itself (bypass, acceptEdits, auto, dontAsk, …). Only default and plan (or a session that hasn't reported a mode yet, such as lwis mcp sessions) receive captures directly;
• you started the session with LWIS_STRICT=1 claude …, or ran lwis sessions strict <sid> on;
• the capture comes from a device with confirm trust, such as the hosted web app. See Your devices.

For a capture from a confirm device, lwis accept <cid> in a terminal also works: the capture is then delivered to its session through the usual rung.

Reply approval

When Claude calls lwis_reply, lwisd keeps the reply until you approve it, and shows a desktop notification.

1. Review the waiting replies in a terminal, not through Claude:

   lwis replies
   

   It prints each reply's id (ra_…), project, recipient and text. Ids are never shown inside Claude, so the model can't approve its own replies.

2. Send one with /lwis:approve-reply <id> in the session, or lwis reply-approve <id> in a terminal.

3. Drop one with lwis reply-deny <id>.

A reply nobody approves expires after 1 hour; lwis log records it as reply_expired.

/lwis:approve-reply without an id only says how many replies wait. Attach with --allow-replies to skip approval for a session.

Statusline

lwis statusline prints a segment for your status line. Compose it into your own command rather than replacing it:

"statusLine": {"type": "command", "command": "input=$(cat); echo \"$(echo \"$input\" | your-statusline) $(echo \"$input\" | lwis statusline)\""}

Audit log and pause

• lwis log lists every delivery (device, session, rung, size, held or confirm), reply, attach and detach, pause and resume, and trust change. Add --json, or -n 100 for more lines.
• lwis pause stops delivery to every session and hosted agent. Captures are acked as queued and kept for up to 24 hours; lwis resume delivers them. You can also pause from a paired device: see Your devices.

Troubleshooting

Start with:

lwis doctor      # dirs, lwisd, pairings, service, browsers, and each session's rung
lwis sessions    # attached or not, strict or held, waiting replies