Skip to content

Latest commit

 

History

History
125 lines (79 loc) · 5.54 KB

README.md

File metadata and controls

125 lines (79 loc) · 5.54 KB

Operator for Claude Code

Turn a normal Claude Code session into a long running autonomous agent with Operator.

TLDR / Quickstart

  • Install the Operator plugin from the Claude Code marketplace.
  • Restart Claude so the plugin, hooks, MCP config, and skills load.
  • On first run, complete the OAuth sign in when prompted so the Operator API key is stored under the plugin folder.
  • In each project directory where you want Operator, run /operator:activate once.
  • Start Claude Code with --dangerously-skip-permissions (recommended, use with a sandbox if you are working in a sensitive environment)
  • Work in natural language while Operator tracks tasks, saves context on each Stop, and decides whether to continue or stop based on directory policy.

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.

What the plugin contains

The 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, UserPromptSubmit, and Stop events to shell scripts.
  • scripts/ contains:
    • session-start.sh for authentication bootstrap and Operator key persistence.
    • pre-prompt.sh for pre user prompt guidance in Operator enabled directories.
    • on-stop.sh for the Operator loop on Stop.
  • skills/ contains the local skill definitions:
    • add-context calls the Operator add context tool.
    • find-context calls the Operator memory search tool.
  • 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

2. Authenticate with Operator

On SessionStart, 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.

3. Run Claude in a sandbox (optional but recommended)

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.

Long running sessions

For long sessions, run Claude in tmux and on macOS you can use caffeinate to keep the machine awake:

caffeinate -dims claude --dangerously-skip-permissions

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.
  • 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

Instead of writing short prompts, ask Claude Code to complete indepth tasks with clear win conditions.

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

Each Claude Code run in an Operator enabled directory is identified by session_id. Per session state is stored in a per session subdirectory under the project, for example .claude/operator/sessions/<session_id>/.

Every time the user sends a message in that directory, Claude Code runs normally until it tries to stop. At the stop boundary, the Stop hook becomes the control point for whether the session is allowed to end. The Stop hook reads the directory config, loads the session state for the current session_id, increments the session turn counter, and applies the configured max_iterations policy for termination of that session.

To find navigation and other pages in this documentation, fetch the llms.txt file at https://docs.operator.io/llms.txt.