Skip to content
DocsAll docs
Console

Claude Code plugin

Install the plugin, sign in and give tasks to a workspace from Claude Code.

Last updated

On this page

Description and operation

General

The Kloudlite plugin lets Claude Code on your laptop work in your workspaces and environments. Claude Code is the AI agent, and it does all its work through the agent tools. No command, file read or file write runs on the laptop. The plugin is part of kloudlite: kloudlite claude writes it to the folder claude-plugin in the kloudlite configuration folder (~/.config/kloudlite) and starts Claude Code with it. It works for one session, and reaches a workspace only through that session.

PartFunction
Tool server klRuns as kloudlite mcp and sends each call through the session.
kl modeRefuses every tool that runs, reads or writes on your computer. /kloudlite:on and /kloudlite:off switch it.
Skills kloudlite, orchestrate, developGive Claude Code the concepts, the rules for a main session and a flow for code changes.
Agents kl-workspace, kl-subagentDo the work in one workspace. The agent of a workspace can ask for subagents.

The main session is the Claude Code session that you talk to. It does not read or change code. It creates, starts, stops and deletes workspaces and environments, and gives each code task to the kl-workspace agent of the workspace that owns the code. It uses the Claude Code tools Agent and SendMessage for this. The file and command tools are those of the tool server of each workspace. An agent ends its work with a report that starts with one of these words.

WordMeaning
DONEThe task is complete.
BLOCKEDThe agent cannot continue. The report gives the cause.
NEEDThe agent needs a decision or information.
SUBAGENTThe agent asks for a subagent for a part of the task.

With kl mode on, a tool that runs, reads or writes on your computer is refused with kl mode: use the kl tools; nothing runs on this laptop. Other tools, such as the web tools, work. kloudlite claude starts Claude Code with kl mode on, but not when you resume a session with -r, --resume, -c, --continue or --session-id. Run /kloudlite:on in that session. This also starts one kl-workspace agent for each running workspace of the session.

The plugin acts with your rights, and a tool over a limit gets the same 409 as any other client. See Limits.

Tasks

Install the plugin

Reason for the task: Make Claude Code on your computer work with the Kloudlite tools.

Job set-up

NOTE

Without -s, the command uses your selected session or your only session, and asks you to choose when there are several. Put arguments for Claude Code after --.

Procedure

  1. Run this command with your team and session names. Leave out -t for your own team.

    CLI
    kloudlite claude -t acme -s dev

  2. Enter your password if the output asks for sudo. This happens on macOS when the environment daemon is old or missing.

  3. Wait for the output line that starts with kl tools:. Claude Code opens after it.

Close-out

  1. Make sure that the output shows session, then kl tools:, a number and ready. Type /mcp in Claude Code to see the server plugin:kloudlite:kl connected.

Sign in

Reason for the task: Give the plugin the credential of your account.

Job set-up

NOTE

kloudlite claude starts this login itself when you are not signed in.

Procedure

  1. Run this command.

    CLI
    kloudlite login

  2. Open the address that the command prints, if the browser does not open.

  3. Make sure that the code on the page is the code in the terminal. Confirm the login.

Close-out

  1. Make sure that the output shows Logged in as and your user name.

Give a task to a workspace

Reason for the task: Make an agent change code in a workspace.

Job set-up

  • Access: you, or your agent. For a team workspace, a team member whose access is not paused.
  • Agent tool: none; an agent uses the SDK.
  • Conditions: Claude Code runs with the plugin and kl mode on, and the workspace exists. The answer arrives when the agent ends its turn.
  • References: Start a workspace, Tool server

Procedure

  1. Type the task in Claude Code. Name the workspace and say what to change.

    text
    In the workspace api, add a /healthz route to the web server and run its tests.

  2. Give an answer when Claude Code asks, for example to start a stopped workspace or to confirm a delete.

  3. Wait for the answer of Claude Code. It states if the agent reported DONE, BLOCKED or NEED.

Close-out

  1. Read the report of the agent. Open the session in the harness to examine the changed files.

Troubleshooting

SymptomPossible causeCorrective action
claude is not on PATH: install Claude Code firstClaude Code is not installed, or its folder is not in the PATH.Install it, add its folder to the PATH and run the command again.
that login expired or was denied — run kloudlite login againThe login code expired, or you denied it.Sign in again.
the kl tools did not answer within 180 s, closed before answering, answered with no tools, or the kl tools failed: …The session did not start, or closed the connection.Run the command again. If it repeats, stop the session and start it again.
choose a session with --session …You have more than one session, none is selected, and the command has no terminal to ask on.Add -s with the session name or id.
environment daemon install failed; run: sudo kloudlite env daemon installThe password for sudo was not accepted, or the install failed.Run the command in the message, then kloudlite claude again.
kl mode: use the kl tools; nothing runs on this laptopClaude Code tried a tool that runs on your computer while kl mode is on.Use a kl tool, or run /kloudlite:off to work on your computer.
403 with your access to acme is pausedA team admin paused your access.Ask a team admin to unpause it.
409 with a limit name, for example workspaces: 5 of 5 in use; request more under QuotaThe owner has no quota left.Delete an unused item, or see Quota and requests.