Skip to main content

​
Overview

The Operator plugin turns a normal Claude Code session into a long running autonomous agent. With a one time OAuth sign in, a per directory enable command, and a Stop hook driven loop, Claude Code can keep working from a backlog instead of stopping after every reply.
  • Install the plugin from the marketplace.
  • Complete the Operator OAuth sign in once when prompted.
  • In each project directory where you want Operator, run /operator:activate and describe goals in natural language.

​
What the plugin contains

The Claude Code Operator plugin uses a standard layout:
  • plugin.json defines the /operator:* control commands such as /operator:help, /operator:activate, and /operator:deactivate.
  • hooks/hooks.json wires SessionStart and Stop events to shell scripts.
  • scripts/ contains:
    • operator-session-start.sh (authentication bootstrap).
    • operator-stop.sh (Operator loop on Stop).
    • A small Operator API wrapper that calls Operator to add context and find context for each turn.
  • A local .mcp.json configures the Operator MCP server so Claude Code can call it as a tool.

​
Install flow

​
1. Install from the plugin marketplace

From inside Claude Code, run: 
/plugin marketplace add operatorlabs/operator-plugins
/plugin install operator
Restart Claude Code once so the plugin, hooks, MCP config, and Skill all load. There is no manual configuration step.

​
2. Authenticate with Operator

On SessionStart, operator-session-start.sh runs and:
  • Starts an OAuth based sign in flow if you have not already authenticated with Operator.
  • Stores the resulting Operator API key under the Claude Code plugin folder so hooks can authenticate without extra setup.
Once authentication succeeds, the session is wired up and can use Operator control commands. If you want Operator to run more freely without putting your machine at risk, run Claude inside a Docker sandbox. If you do not already have Docker, install Docker Desktop or the Docker CLI from docker.com and make sure docker version works. Then start a sandboxed Claude session in the current directory: 
docker sandbox run claude
Inside the sandbox, start Claude with permissions skipping so Operator can use tools without stopping for every approval: 
claude --dangerously-skip-permissions
This setup is optional but strongly recommended. It gives Claude and Operator room to work while keeping the rest of your system safe.

​
Enable Operator for a directory

When the session status is ready, you enable Operator management for the current directory with: 
/operator:activate
/operator:activate:
  • Creates a hidden project config directory for Operator in the current working directory if one does not already exist.
  • Writes a project local config file with the directory policy, including max_iterations and other loop settings.
  • Is idempotent and reports when Operator is already enabled for that directory.
From here, you talk in plain language. You do not manage hooks or config files directly. You can see a short summary of how Operator behaves in the current directory with: 
/operator:help
To turn Operator off for a directory, run: 
/operator:deactivate
This removes the project local config and any session state so future runs in that directory behave like normal Claude Code sessions. All /operator:* commands are treated as control operations. They skip the Stop hook loop, do not increment turn counters, and are not persisted into Operator memory.

​
Adding tasks and goals

After you run /operator:activate in a directory, you describe short term tasks and long term goals in natural language. Operator Memory is the external store of goals, tasks, and notes that the agent uses between stops. On each Stop, the hook writes the latest turn into Operator via the add-context API and then calls Operator again to find relevant context and decide what to do next. You do not call any Claude Skills directly for this. You keep talking in plain language while Operator manages tasks and goals behind the scenes.

​
Operator loop via the Stop hook

In an Operator enabled directory you keep coding normally. After each reply, the Stop hook decides whether Claude should keep going or stop. At a high level:
  • If there is no project config or the last prompt was an /operator:* command, Claude stops like normal.
  • Otherwise the hook saves the last turn into Operator, asks Operator what to do next, and applies the directory max_iterations cap.
  • When Operator says to continue and the cap is not reached, Claude gets new instructions and runs another loop.
  • When Operator says <<STOP>>, the hook cleans up temporary per run state and ends the run immediately without inserting /compact or extra guidance.
  • When a run ends for a given session_id, temporary per run state is cleared so the next run starts clean.
This matters in common flows:
  • Debugging: you ask Claude to trace and fix a bug. Operator keeps the loop going while there is useful next work, then ends the run once the fix is wrapped up.
  • Large refactor: you describe the target state and constraints. Operator steps through edits, testing, and clean up, then ends the run once the refactor is complete.
  • Multiple tasks in one Claude session: after a run ends, you can give a new task in the same Claude Code session. The next Stop treats it as a fresh run for that session_id with a reset turn counter, while long term context still comes from Operator memory.

​
TLDR

  • Install the plugin and authenticate once.
  • In each project directory where you want Operator, run /operator:activate once.
  • Work in natural language while Operator tracks tasks, saves context on each Stop, and decides whether to continue or stop based on directory policy.