Open WebUI Claude Agent Pipe

An Open WebUI pipe function that
runs each chat turn as a headless Claude Agent SDK
session: Claude Code's full agent loop, with a real working directory and
tools, behind a normal chat UI, billed to an Anthropic API key or, on a
single-user install, your Claude subscription. It is for
one person (or one trusted admin) who already runs Open WebUI and wants Claude
Code in it, on the web and on mobile clients, rather than only in a terminal.

The agent can stop mid-turn and ask through Open WebUI's own form:

Every reply ends with what the turn cost:

Credit

This is a fork of Thomas Friedel's
openwebui-claude-code
(MIT), taken at commit 5bbc1fc. He built the bridge: the pipe, the valves,
the knowledge-base tools, inline tool details, image attachments, and the
artifact scanner are his work and still form the backbone of this file. This
repo adds durable sessions, output redaction, the status stream, ask_user,
chat search, and the rest of the changelog on top, and
maintains it now that upstream has gone quiet. If you find it useful, his
repo is where the idea came from.

Features

• Real agent loop — Read/Write/Edit/Bash/Glob/Grep/WebSearch/WebFetch and
  subagents, in a per-chat working directory, streamed token by token.
• Durable sessions — each chat maps to one Claude Code session that
  survives Open WebUI restarts and function redeploys (in a container, set
  CLAUDE_CONFIG_DIR to a persistent path too); a cold start replays the
  chat history once and resumes warm from then on.
• Keyless clients — OpenAI-API callers that send no chat id (mobile apps,
  voice) get a session too, fingerprinted from the conversation prefix.
• Live status — tool activity, a heartbeat while a tool runs, subagents
  grouped under their parent, and a Done · 1m42s · 74k/200k (37%) · 12 tools
  line at the end; the message's ⓘ usage popover also gets the turn's
  duration and the subscription's usage windows (session, weekly, per-model,
  extra usage) with the time left until each resets.
• ask_user — the agent can pause and ask up to three multiple-choice
  questions through Open WebUI's own form, and get the answers in the same turn.
  The questions also appear in the reply, and typing an answer in the chat
  works when the form is not showing.
• Earlier chats — search_chats / read_chat let the agent look up the
  calling user's past conversations (sqlite deployments; read-only; scoped to
  that user).
• Knowledge bases — a Workspace Model's attached knowledge becomes
  search_knowledge / list / read / grep tools the agent calls itself.
• Images and artifacts — attached images are written to the workdir for
  the agent to read; files the agent creates in the workdir (and in /tmp,
  if SCAN_TMP_ARTIFACTS is on) come back inline or as links.
• Repo-rooted chats — #repo:<name> on a first message runs the chat
  inside an allowlisted repository (and loads its CLAUDE.md when
  SETTING_SOURCES includes project).
• Output redaction — API keys, tokens and private keys are scrubbed from
  the reply stream and status events before they reach the chat database.
• Effort, budget, fallback — per-chat Reasoning Effort or per-turn /effort <level>, a task token
  budget the model paces itself against, and a fallback model.
• Cold-resume guard (opt-in, COLD_RESUME_GUARD) — a message to a large
  chat idle past the prompt cache gets a cost warning and a pickup note for a
  new chat instead of a full-price context rebuild; continue or /resume
  goes ahead.

Requirements

• Open WebUI with the Functions framework; tested on 0.11.3.
• The Python Open WebUI runs on (3.11 or newer). claude-agent-sdk 0.2.152
  or newer is installed by Open WebUI from the file's requirements: line
  and bundles the Claude Code CLI, so no Node.js and no separate claude
  install on the host.
• An Anthropic API key from the Claude Console,
  or, for a single-user install, a Claude Pro/Max/Team subscription (one-time
  claude setup-token on any machine with a browser). See
  Which credential before choosing.
• A directory the Open WebUI process can write, for WORKDIR_ROOT.

Tested on macOS 15 (native install) and on Linux as root in the official
ghcr.io/open-webui/open-webui:main image, with Open WebUI 0.11.3,
claude-agent-sdk 0.2.152, Claude Code CLI 2.1.259.

Install

Five steps: a credential, the function, its valves, the toggle, a first message.

1. Get a credential

API key (recommended). Create one in the
Claude Console. Billed per token. This is the
path Anthropic's docs name for products built on the Agent SDK
(Legal and compliance,
"Authentication and credential use"), and the only one to use on any
instance with more than one user.

Subscription token (single-user installs only). On any machine with a
browser and Claude Code installed:

claude setup-token

Copy the long-lived OAuth token it prints. It authenticates your own
Pro/Max/Team subscription for your own use. Anthropic currently counts Agent
SDK usage against subscription limits and says it is still working out how
plans should cover it; its docs also say SDK-based products should use an API
key, and its position on subscription use outside Claude Code has changed
before. Treat this path as unsupported and subject to change. Never put a
subscription token on an instance other people use: routing other people's
requests through your plan is what Anthropic's terms forbid outright.

2. Add the function

In the UI: Admin Panel → Functions → +, paste the contents of
claude_agent_pipe.py from the latest release
(the file on main may be ahead of the changelog), set the id to claude_code
and any name, Save.

Or over the admin API (bash, from the repository root):

curl -sf -X POST http://localhost:8080/api/v1/functions/create \
  -H "Authorization: Bearer $OWUI_ADMIN_KEY" -H 'Content-Type: application/json' \
  --data-binary @<(python3 -c 'import json;print(json.dumps({"id":"claude_code","name":"Claude Code","meta":{"description":"Claude Code agent loop"},"content":open("claude_agent_pipe.py").read()}))')

Either way, Open WebUI installs claude-agent-sdk from the file's
requirements: line on save. Allow a minute. Two things can go wrong:

• The save fails with "Error creating function": the install did not
  succeed. Check the Open WebUI log for the pip error.
• The host runs with OFFLINE_MODE=true: Open WebUI skips the install
  entirely. Install the SDK into Open WebUI's Python environment yourself
  (pip install 'claude-agent-sdk>=0.2.152') and save again.

3. Set the valves

Functions → Claude Code → ⚙ Valves. Two matter on first install:

• ANTHROPIC_API_KEY, or CLAUDE_CODE_OAUTH_TOKEN on a single-user
  install: the credential from step 1. If both are set the token wins and
  the key is unset for the agent.
• WORKDIR_ROOT: a directory the Open WebUI process can write. The default
  is /tmp/claude-agent-pipe; use a persistent path so sessions survive
  reboots.

In a container, also set CLAUDE_CONFIG_DIR to a persistent path (for
example a subdirectory of a bind-mounted WORKDIR_ROOT). The Claude Code
CLI keeps its session transcripts there; left at the default they live in
the container's $HOME/.claude and vanish when the image is recreated.

Chat titles, tags and follow-up suggestions come from Open WebUI's Task
Model (Admin → Settings → Interface). With none set, Open WebUI asks the
chat's own model, and the pipe answers with one short tool-less call on
TASK_MODEL (Haiku by default). A local Task Model costs nothing per chat.

Read the Security section before leaving PERMISSION_MODE at
its default. Every other valve is described in
docs/valves.md, generated from the code so it is always
current.

Over the API, valves are a JSON object posted to
POST /api/v1/functions/id/claude_code/valves/update.

4. Enable it

Flip the toggle on the Functions page (or
POST /api/v1/functions/id/claude_code/toggle), then pick Claude Code in
the model picker. MODELS adds one picker entry per extra model id; the API
model id is claude_code.claude-code.

5. Send a message

The status line shows Session: new chat, then tool activity, then the Done
line. A second message shows Session: resumed.

Uninstall

Disable and delete the function in Admin Panel → Functions, then remove
WORKDIR_ROOT (and CLAUDE_CONFIG_DIR if you set one). Nothing else is
written outside those two directories and Open WebUI's own database.

How it works

pipe() is called once per turn. It resolves the working directory
(WORKDIR_ROOT/<chat_id>, or anon-<uuid> for keyless callers, or the
#repo: target), decides whether a Claude Code session can be resumed, and
runs the turn through ClaudeSDKClient, translating the SDK's message stream
into text chunks and Open WebUI status events.

• Sessions. The chat id → session id map is persisted to
  WORKDIR_ROOT/.sessions/<chat_id>.json; the in-process dict is only a
  cache. Keyless callers are fingerprinted from their conversation prefix into
  WORKDIR_ROOT/_sessions.json (entries expire after 30 days). A dead resume
  id is dropped and the turn is retried cold.
• Cold starts. When no session can be resumed, the prior turns are packed
  into a <conversation_history> block ahead of the prompt (last 30
  messages, 24k chars), so nothing is lost; the next turn resumes warm.
• Tools. Everything Claude Code has, gated by ALLOWED_TOOLS and
  PERMISSION_MODE, plus in-process MCP servers for ask_user, chat search,
  and knowledge. Those are registered with alwaysLoad because Claude Code
  2.1 otherwise hides MCP tools behind ToolSearch and the model never
  finds them.
• The agent's environment. The chat id is exported to the agent's
  subprocess as HUB_CHAT_ID (only when one exists), so tooling the agent
  runs can find out which chat it is serving. Nothing in this repo reads it.
• Redaction. Every chunk and event passes through _redact_secrets
  before leaving pipe(). A hit is logged by kind, never by value.

Security

Read this before exposing the function to anyone but yourself.

• bypassPermissions is the default. Every user who can pick the model
  runs arbitrary code as the Open WebUI process user, on the Open WebUI host,
  with no prompts, using your credential. Treat the function as a shell for
  everyone it is enabled for. Restrict it to admins in Open WebUI's model
  access controls, or tighten PERMISSION_MODE and ALLOWED_TOOLS.
• Valves are global. One token, one WORKDIR_ROOT, one REPO_MAP for
  every user of the function. Two users cannot read each other's chats
  (chat search is scoped by user id) but they share the filesystem and the
  credential. This is a single-user or single-admin design, and with a
  subscription token it must be single-user: see step 1 of the install.
• REPO_MAP hands out paths. Anyone who can start a #repo: chat runs
  the agent inside that repository. It grants nothing bypassPermissions
  did not already reach; it only sets the working directory.
• SETTING_SOURCES loads the host user's ~/.claude (with user),
  which can define hooks that execute code. Leave it empty unless you
  control the host account; see Persistent context.
• What the redactor catches: prefix-shaped credentials (Anthropic,
  OpenAI, Slack, GitHub, Google, AWS, 1Password, JWTs) and PEM private keys,
  in the reply and in status events. What it cannot catch: bare UUID
  tokens, passwords, hostnames, or anything that looks like prose. The
  agent can still cat a secret into a file the chat never sees. Keep
  credentials out of WORKDIR_ROOT and the mapped repos, or give the agent
  a hook (Claude Code's PreToolUse) that refuses to publish them.
• Running as root (the official Docker image does) makes the CLI refuse
  bypassPermissions unless IS_SANDBOX=1; the pipe sets it. That is the
  CLI's own sandbox flag, not an actual sandbox.

Report a vulnerability as described in SECURITY.md.

Persistent context

By default the pipe passes setting_sources=[] to the SDK: each chat starts
from a clean baseline and inherits nothing from the host user's ~/.claude/
or the workdir's .claude/. That is the safe default for anything shared.

On a single-user instance, standing instructions in ~/.claude/CLAUDE.md
(a host inventory, house rules) can be loaded into every chat with the
SETTING_SOURCES valve:

Unknown tokens are dropped. There is no way to load a CLAUDE.md without
also loading the settings.json next to it: that coupling is Claude Code's,
not the pipe's, and settings.json can define hooks that run shell commands,
permission grants, environment variables and MCP servers, for every chat,
as the Open WebUI process user, under bypassPermissions. With
CLAUDE_CONFIG_DIR set, user reads from that directory instead of
~/.claude.

Open WebUI coupling

The pipe imports a few Open WebUI internals. Each import is wrapped so a
version that moved them degrades a feature instead of failing the turn:

Chat search reads the sqlite chat table directly and is off by construction
on Postgres deployments (DATABASE_URL starting with postgres makes the
tools report unavailable).

Claude Code CLI coupling: alwaysLoad on SDK MCP servers (2.1.x), the
subagent tool being named Task or Agent (both handled), and ToolSearch
deferral. test_turn.py pins the name cases.

Files

• src/*.py — the source, one module per concern, concatenated in filename
  order into the built file. Edit these, never the built file.
• claude_agent_pipe.py — the built function: what you install and what
  the redaction consumers slice. python3 build.py regenerates it (and
  docs/valves.md); python3 build.py --check fails CI when either is stale.
• redact_stdin.py — a CLI over the pipe's redactor for job workers that
  deliver agent output outside the chat stream (--known-env scrubs live
  values by value, not just by shape). Optional; the pipe does not need it.
• test_*.py — standalone suites, stdlib only: python3 test_sessions.py,
  optionally against a deployed copy (python3 test_sessions.py <pipe.py>).

See CONTRIBUTING.md for the development loop and
CHANGELOG.md for what changed on top of upstream.

Updating a deployed copy

Merging here deploys nothing: Open WebUI runs the copy stored in webui.db.
Paste the new claude_agent_pipe.py over the function in Admin → Functions,
or post it to POST /api/v1/functions/id/claude_code/update with the same
JSON shape as the create call. Valve state lives in webui.db and survives
redeploys. The author's own deploy wrapper (backup, post, verify parity, run
the suites against the deployed copy) lives in a separate homelab repo and is
not needed to use this one.

License

MIT, see LICENSE. Copyright is shared with the upstream author, as
the file says.