Claude Code Integration

Claude Code Integration

Nautelle is not only for the fleet. The nautelle Claude Code plugin makes the sessions you start by hand first-class: they show up in Nautelle, they can track their work as Board cards, they can read the fleet, queue and budget, and while you are away their permission prompts can be approved from the web app or Telegram. Everything goes through the runner on your machine; the plugin never talks to the server itself.

Overview

Part	What it gives you
Hooks	report the session's lifecycle to Nautelle: start, prompts, tool use, permission requests, notifications, stop, compaction, end
MCP server (nautelle)	15 tools the model can call against Nautelle
Slash commands	/nautelle:away and /nautelle:handoff
Skill track-work	tells the model to put the work you ask for on the Board
nautelle-runner claude	starts Claude in a tmux session that Nautelle can attach to

How it works

flowchart LR
  CC["Claude Code session"] -- "hooks" --> H["nautelle-runner hook <event>"]
  CC -- "MCP (stdio)" --> M["nautelle-runner mcp"]
  H -- "local socket" --> D["Runner daemon"]
  M -- "local socket" --> D
  D -- "outbound WebSocket" --> API["Nautelle API"]

Loading

1. The hook commands and the MCP server are subcommands of the same nautelle-runner binary.
2. They talk only to the runner daemon on the same machine, over a user-owned local socket. The runner token never leaves the daemon.
3. The daemon relays typed requests to the API over its existing connection. Each method has a minimum role.
4. Local requests act as the runner's local user (assigned by an admin; by default the admin who created the runner), capped at operator. Every write is audited with the runner as actor and the local user as onBehalfOf.
5. Writes that need a person — starting or stopping the orchestrator, approving a pull request, approving a tool call while you are away — are never executed on request. They become an action request that a person approves.

Setup

Install the plugin and point Claude Code's telemetry at the runner:

nautelle-runner setup claude

Option	Effect
--profile <key>	only this Claude runtime profile (default: every Claude profile the runner knows)
--no-telemetry	install the plugin only; leave settings.json alone
--dry-run	print the plugin commands and the settings diff without writing
--uninstall	reverse both steps

For each profile it installs the plugin at user scope and merges the OpenTelemetry exporter settings into the profile's settings.json (writing a .bak first). It is idempotent.

Tip

Start sessions with nautelle-runner claude [-- <args>] instead of claude. In a terminal with tmux it runs Claude inside an nautelle-manual-* tmux session, so an admin can watch or attach to it from the session page. Without a TTY or tmux it simply runs claude.

MCP tools

Claude shows them as mcp__plugin_nautelle_nautelle__<tool>.

Tool	Role	What it does
status	viewer	the project's fleet: orchestrator state and every slot with its issue, state and last activity
queue	viewer	queued issues: number, title, labels, ready, already in flight
budget	viewer	remaining budget of the project and of the local user, per scope and period
approvals	viewer	pull requests waiting for approval and pending action requests
activity	viewer	the most recent activity events of the project
sessions	viewer	the most recent agent sessions of the project
action_status	viewer	the state of an action request
create_issue	operator	create a GitHub issue; with queue: true a person must approve queuing it
note	operator	post a short note to the project's activity feed
handoff	operator	record an issue with the state of a branch so someone else can continue; a person approves it for the fleet
request_action	operator	ask a person to start or stop the orchestrator, or approve a pull request
away	operator	turn away mode on or off for this runner
track_card	operator	track the work you just asked for as a Board card In progress, linked to this session
finish_card	operator	only for a Board card worker: report the card done with a summary; Nautelle opens or updates the PR
resume_context	local	the card's handoff note, read from the machine — never through the server

Tracking terminal work on the Board

With the track-work skill, when you ask the model to do work — implement, fix, change or refactor — it calls track_card once before it starts. Questions, explanations, reviews and code reading are not tracked.

1. The card appears In progress with source terminal, linked to the session. No worker is started.
2. A second call from the same session updates that card; it never creates another.
3. When the session ends (or finish_card runs), the card moves to Finished.
4. Only a person moves it to Completed.

Nothing is pushed for a tracked card unless its automatic work option is on (the board setting defaults it to off): it is your own work on your own branch.

Away mode

While away mode is on, a permission prompt in any plugin-enabled session on that runner goes to a person instead of waiting at the terminal:

1. The session asks for a permission.
2. The runner creates a tool_use action request with a redacted preview of the tool input — always, whether or not the project ships session content. Long input is sent as head and tail with a marker, plus its length and hash.
3. You Approve or Deny in Approvals or from the Telegram notification.
4. Approved → the tool runs. Denied → the model gets your note. Expired or offline → the local dialog shows as usual.

Turn it on or off with /nautelle:away on|off, nautelle-runner away on|off, the away tool, or the runner's toggle in Admin › Runners. Switching it off sends a "while you were away" Steward digest.

Handing work to the fleet

/nautelle:handoff [title] (or the handoff tool) files the current work as a GitHub issue with what is done, what remains and the branch.

Important

A session never adds the ready label itself. An issue it files with create_issue {queue: true} or handoff is created unqueued, together with an issue_queue action request. The fleet picks it up only after a person approves it in Approvals or Telegram.

Messaging a running session

From a card, a fleet slot or Telegram, an operator can type a message into a running session or answer a Claude question selector with the shown options. The text is cleaned (no control or escape characters, at most 4,000 characters), typed into the session's input, and audited by hash and length, never by content. Text sent while the agent works is queued by Claude Code until its next step. For fleet workers, the orchestrator's own event log records the message, so it knows what each worker was told.

Session content

By default a project ships metadata only. A project admin can turn on session content (Project › Settings › Sessions), with a retention of 1–365 days (default 30). Then hook payloads — prompts, responses, tool input and output — are redacted on the runner, capped at 16 KiB per text, and stored for project members to read. Turning it off stops shipping; an admin can purge stored content at once.

Session content also enables card capture (a small model suggests Inbox cards from manual sessions) and lets Context Handoff notes be edited from the web.

See also

• Context Handoff · Token Saver · Telegram · Steward
• Runner commands: apps/runner/README.md

Decisions: ADR-0020 · ADR-0021 · ADR-0026 · ADR-0030 · ADR-0045 · ADR-0050 · ADR-0051 · ADR-0052 · Spec: #201, #489