claude-cloak
A TUI that displays Claude Code's streams token-by-token — thinking, text, and tool calls — by sitting as a pass-through proxy between Claude Code and the Anthropic API.
No extra usage: it never issues requests of its own; it observes the SSE stream of requests Claude Code was already making, forwarding bytes verbatim and unbuffered.
claude ──ANTHROPIC_BASE_URL──▶ claude-cloak (127.0.0.1:8484) ──▶ api.anthropic.com
│
▼
TUI: live token feed
Usage
The build links with mold (see
.cargo/config.toml), so install it first.
cargo build --release
./target/release/claude-cloak
To put it on your PATH, run cargo install --path . --locked. It reuses
target/release, so after cargo build --release it compiles nothing.
Without --locked, cargo ignores Cargo.lock, picks newer dependency versions
and compiles everything that depends on them again.
Nightly builds
The home server builds main every night when it has new commits: for x86_64
and aarch64 Linux (glibc 2.31 and newer) and for Termux. To install one:
curl -fsSL 'https://gitea.haugesenspil.dk/api/v1/repos/jonas/claude-cloak/raw/dev/install?ref=main' | sh
It puts claude-cloak in ~/.local/bin ($PREFIX/bin in Termux, or
CLOAK_BIN_DIR). Then:
claude-cloak updateinstalls the newest nightly. Running instances switch to it onprefix r.claude-cloak update --checkonly says whether there is a newer one.claude-cloak versionshows which build you run.
update leaves a build of your own (cargo install) alone unless you add
--force.
Plain claude-cloak runs hosted. It starts a small daemon if none runs, and
the daemon keeps your instance in a pty. If the terminal closes or crashes,
the instance and its claude panes keep running. Run claude-cloak again in
the same folder to get it back.
| Command | What it does |
|---|---|
claude-cloak |
reattach to this folder's detached instance, or start one |
claude-cloak new |
start a new instance |
claude-cloak attach [id] |
attach to an instance (the latest detached one); it takes the instance from another terminal |
claude-cloak ls |
list instances and their panes |
claude-cloak status [--watch] [--json] |
one summary of every pane; --watch prints a JSON line per change (for a status bar) |
claude-cloak focus <id> [pane] |
focus that instance's terminal (sway), or open one |
claude-cloak kill <id> |
end a hosted instance |
claude-cloak run [-m up/model] [--json] [--continue | --session <id>] [--cwd <dir>] [prompt] |
one native turn for a script (see Scripting) |
claude-cloak login <provider> / logout <provider> |
store or remove an API key for a preset (openrouter, opencode-go, …) |
claude-cloak daemon [start|stop [--force]|reload|status] |
manage the daemon; stop refuses while instances run |
claude-cloak --standalone |
run in this terminal without the daemon; it ends with the terminal |
daemon reload swaps the daemon onto a new binary. Instances and clients
keep going. Daemon log: $XDG_STATE_HOME/claude-cloak/daemon.log.
Then point Claude Code at the proxy, either per-shell:
export ANTHROPIC_BASE_URL=http://127.0.0.1:8484
claude
or globally in ~/.claude/settings.json:
{ "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:8484" } }
Note: with the global setting, Claude Code can't reach the API while the proxy isn't running.
Termux (Android)
cloak runs in Termux on an aarch64 Android phone. The nightly install above
works in Termux. To build it yourself, cross-build it on a Linux
machine with the Android NDK (rustup target add aarch64-linux-android, and
ANDROID_NDK_HOME if the NDK is not under ~/Android/Sdk/ndk):
dev/android-build # prints target/aarch64-linux-android/release/claude-cloak
Copy that file into a folder on Termux's PATH, such as $PREFIX/bin. Then,
on the phone:
- Claude Code has no official Android build. Community packages patch Anthropic's arm64 build so it runs in Termux.
- Run
termux-wake-lock, so Android does not stop Termux while the screen is off. On Android 12 and later, also turn off the child process limit in the developer options. - Termux has no sound player for the chime. For a notification, install the
Termux:API app and
pkg install termux-api, thenexport CT_NOTIFY='termux-notification -t "$CLOAK_TITLE" -c "$CLOAK_BODY"'before the daemon starts. - Put a Nerd Font in
~/.termux/font.ttffor the frames' glyphs. - Termux's clipboard holds only text. To attach an image, paste its path
(
termux-setup-storagegives Termux your shared storage).
Touch mode turns on by itself in Termux. To have it turn on in cloak on
another machine you reach with ssh from Termux, put this in Termux's
~/.ssh/config:
Host *
SetEnv LC_TERMINAL=Termux
Most sshd configurations pass LC_* variables (AcceptEnv LANG LC_*). Where
one does not, or over mosh, start cloak with CT_TOUCH=1.
Notifications
A pane that finishes, fails or asks while you do not look at it makes the
daemon play a chime. Set notify in config.toml (or CT_NOTIFY in the
daemon's environment, which wins) to off, or to a command. The daemon runs
the command with sh -c and these variables:
| Variable | Value |
|---|---|
CLOAK_TITLE |
the pane's title, one line |
CLOAK_BODY |
the status, then · session <id> when the pane has a session |
CLOAK_STATUS |
idle (a turn finished), needs an answer or error |
CLOAK_SESSION |
the full session id (empty before the first request) |
CLOAK_URGENCY |
critical for an ask or an error, else normal |
CLOAK_PANE |
the pane token, for claude-cloak send |
CLOAK_CWD |
the folder of the instance that owns the pane |
CLOAK_AWAY |
1 in away mode, else 0 |
CLOAK_KIND |
claude or native |
CLOAK_ASK |
what an ask waits on: permission, question, plan, elicitation or dialog, else empty |
CLOAK_ASK_JSON |
the ask as the screen shows it (below), else empty |
claude-cloak away on|off|toggle sets away mode, and claude-cloak away
prints on or off. The daemon keeps it in
$XDG_STATE_HOME/claude-cloak/away (default ~/.local/state), so it
survives a restart. In away mode the pane on screen notifies too.
status --json and status --watch show it as "away": true.
claude-cloak send <pane> [text...] submits the text in that pane, as if you
typed it in cloak's editor and pressed Enter. With no text, or -, it reads
the text from stdin. A message to a busy claude pane goes into Claude Code's
queue; one to a busy native pane steers its turn. A pane that waits on a
permission dialog or a question refuses it (pane <tok> is waiting on a dialog; answer it at the desk, exit 1). A message that cannot go out within
10 minutes is dropped. The text can be at most 64 KiB. So a notify command can
send to your phone when you are away, and your answer can go back to the pane
that asked:
CLOAK_ASK_JSON is at most 8 KiB:
{"kind": "permission", "title": "Read file", "tool": "Read",
"detail": "Read(/etc/os-release) · Do you want to proceed?",
"choices": ["Yes", "Yes, allow reading from /etc during this session", "No"]}
{"kind": "question", "tool": "AskUserQuestion",
"questions": [{"question": "Which features?", "header": "Features", "multi": true,
"options": ["Logging", "Metrics"], "other": true}]}
choices are a dialog's numbered options in screen order; questions are a
question panel's, each with a free-text other row.
claude-cloak answer <pane> <choice>... [--text T]... answers it:
- a dialog (
permission,plan,dialog): one option number, orallow(yes,y: option 1) ordeny(no,n: the lastNo…option). With--text, the option is amended where the dialog's hint offersTab to amend:answer <pane> no --text "use cat instead"is Claude Code's "No, and tell Claude what to do differently". A native pane's approval has1Yes,2Yes and stop asking,3No; a text after its No steers the agent. - questions: one choice per question, in order:
2,1,3for several options of a multi-select question,other(or2,other) for the free-text row, which takes the next--text.answer <pane> --text "…"alone answers a single question's free-text row.
It exits 1 with the reason when the answer does not fit what the pane shows
(pane <tok> has no permission dialog, … has 3 options, not 4, … asks 2 question(s); give one answer for each, … takes no text). A question left
in Claude Code's own dialog (ctrl-o at the desk) and an MCP form with fields
to type are refused: answer them at the desk.
notify = '[ "$CLOAK_AWAY" = 1 ] && my-phone-push "$CLOAK_TITLE" "$CLOAK_PANE" || claude-cloak chime "$([ "$CLOAK_STATUS" = idle ] && echo done || echo ask)"'
Keys
Everything you type goes to the embedded claude. There is no focus model and
no key you have to think about — q, j and Esc all reach Claude Code,
because the app's own keys live behind a prefix, tmux-style.
Press ctrl-space and a which-key popup shows what is available. The keys work immediately; you never have to wait for the popup.
^space + |
action |
|---|---|
s |
the session group: s sessions, c continue, t tree, h handoff, a streams, e effort (below) |
p |
new pane (model picker) — Claude Code models, then native ones |
n |
new session (model picker), replaces the current pane in its tab |
x |
close the pane |
w |
the panes, as a list |
1-9 |
go to that pane |
m |
switch the model of the active pane |
i |
info about the active pane's upstream — one tab per upstream: plan windows, credit, spend, prices, context, speed, rate limits (see Upstream info) |
/ |
find bar — matches highlight in place, enter/↓ next, ↑ prev, with a 3/12 counter |
] [ |
next / previous user prompt |
. |
back to the live main chain, tailing it — undoes a picked session, a picked lane, and a parked scroll |
: |
terminal — the fenced blocks of the session as snippets, and a command field that runs in a panel (enter runs, r runs it again, e edits it) |
y |
copy the pane's last answer to the clipboard |
f |
filter which entry kinds show |
l |
the changes group: g lazygit, b leaderboard (below) |
c |
the claude group, for keys that only act on a claude pane: n native agents, p peek (below) |
r |
hot reload |
s s |
sessions — type to find, ↑/↓ previews each one in the feed, enter opens it, Esc keeps reading it. Tab gives the keys to the list: turn tree with space, branch with b, r renames, d deletes or hides, n shows named ones, H shows hidden ones, u undoes a hide (see The session list) |
s c |
continue the most recent session |
s t |
the session tree of the active pane |
s h |
handoff of the active pane's session (see Handoff) |
s a |
streams — j/k previews the main chain, each subagent, each hosted tool call. Sized to the list, capped at a third |
s e |
the effort of the active pane, picked from a list |
l g |
lazygit in a box over the screen, in this folder |
l b |
the leaderboard of the session's most-edited files: off, 3, 5 or 10 rows |
c n |
native agents a claude pane may call, and the models they may run on (see Native agents a claude pane calls) |
c p |
peek: the claude pane's real screen, whole, with the keys to Claude Code. Press it again to go back |
d |
the instance group: d detach this terminal, k kill this instance and all its panes, m the instances |
Repeatable keys (] [) keep the popup open, so ^space ]]] walks.
^space ^space sends a literal prefix to the child.
Two keys are the app's without a prefix, for the same reason a terminal keeps
them for itself: the wheel and shift+PgUp/PgDn scroll the feed (or the
pane's own scrollback while you peek at it). They keep working while a
list is open, so you can read what you highlighted before committing to it.
ctrl+shift+←/→ walk the panes, and ctrl+d detaches this terminal (the
same as ^space d d). ctrl+d never reaches Claude Code or the native editor:
Claude Code would exit on it, and the editor's delete-forward is still on
Delete. A standalone instance has nothing to detach and says so. prefix in
keys.toml cannot be ctrl-d.
Esc closes the topmost overlay. With nothing open it goes to Claude Code, so interrupt and Esc-Esc rewind keep working. Filters and the stream you picked are settings, not modes — Esc never resets them.
CT_PREFIX changes the prefix (CT_PREFIX=ctrl-b, ctrl-], f1, …), for the
case where your Claude Code wants ctrl-space for itself. CT_DEBUG_KEYS=1 shows
what your terminal actually delivers. ctrl-q quits from anywhere, as a way out
if the prefix never arrives.
Your own keys
~/.config/claude-cloak/keys.toml ($XDG_CONFIG_HOME is honoured; CT_KEYS
names another file) edits the table above. Press ^space r after you edit it.
The popup shows one layer at a time with a breadcrumb (^space › g cargo);
Esc goes back one layer, then closes. A group is a key with a second layer:
^space g r. Two layers is the limit. s and d are built-in groups; a table
on their key edits them.
prefix = "ctrl-b" # CT_PREFIX wins over this
"u" = "sessions" # move a built-in action to another key
"r" = "none" # unbind
"S" = { action = "streams", label = "lanes", keep = true } # keep the old key too
"!" = { run = "make", label = "build" } # runs in the run panel, like a snippet
"h" = { send = "hello" } # pasted into the active pane; nothing submits
"H" = { send = "hello\n" } # a trailing newline presses Enter after it
[g] # a group
label = "cargo"
r = { run = "cargo run", label = "run" } # ^space g r
t = { run = "cargo test" }
b = "filter"
Put top-level keys above the first [group] line, or TOML files them in it.
A run command runs in the folder of the panes ($SHELL -c).
A send text goes into the claude child or the native editor as one paste. Only a trailing \n submits it.
A key you bind replaces the built-in on that key. A bad entry (unknown action, a key twice, Alt, a third layer, digits 1-9) is skipped with the reason in the status line; the rest of the file still applies.
Action names: sessions streams new_session new_pane continue panes
goto_pane (the digits, fixed) kill_pane filter search terminal
next_prompt prev_prompt follow_live peek
manager detach reload quit tree handoff model effort info copy_answer leaderboard native_agents, and next_pane prev_pane.
Upstream info (^space i)
^space i shows what cloak knows about the upstream of the active pane. It has
one tab per upstream: claude (Claude Code's own), then each upstream of
providers.toml. It opens on the active pane's tab. Tab/←/→ switch tabs,
↑/↓ scroll, r asks again, Esc closes.
- Plans (Claude, OpenCode Go): the 5-hour, weekly and monthly windows with their resets, the limit state, a pace forecast (where the use ends at the pace so far) and, for OpenCode Go, each model's monthly limit.
- Pay per token (DeepSeek, OpenRouter, …): the credit left (DeepSeek, OpenRouter and Moonshot have a balance endpoint), this session's tokens and cost by model, the spend today, this week and this month over all native sessions, and the prices (DeepSeek's peak and off-peak, and when they switch).
- Every tab: the context fill and cache hit of the active pane, the speed (time to the first token, tokens per second), requests, retries, errors, and the upstream's rate-limit headers.
It spends no tokens. Claude's windows and the rate limits come from the headers of answers that pass through anyway. The credit and a plan's usage are read-only GETs, asked only while the tab is shown and at most once a minute. The counts start over after a hot reload.
Native sessions
A native pane is a coding agent that claude-cloak runs itself, for models
Claude Code cannot talk to: a local llama.cpp or Ollama server, OpenRouter,
DeepSeek, or Anthropic with an API key. It has an input box instead of a
claude screen. Behind the tab a child process, claude-cloak agent, runs the
loop: it sends your prompt, runs the tool calls the model asks for and sends
the results back. Every request goes through the proxy, so the feed shows it
like any other stream.
Nothing is sent until you submit a prompt. No title, summary or warm-up request goes out. The one other request is model discovery (below): a read-only GET of the upstream's model list that costs no tokens.
What the agent reads
The system prompt carries the working folder, the date, the OS, and these files, each once, with its path as a header:
~/.config/claude-cloak/AGENTS.md($XDG_CONFIG_HOMEis honoured);- in every folder from the git root down to the working folder:
AGENTS.md,CLAUDE.md, thenCLAUDE.local.md. Outside a repo the walk starts at your home folder (or/when the folder is not under it).
Your ~/.claude/CLAUDE.md is not read: it tells Claude Code how to use Claude
Code's own tools and agents. A file over 32 KB is cut, and the files together
stop at 128 KB. Both show a marker. A folder below the working folder with its own AGENTS.md or
CLAUDE.md is read the first time a tool touches a path in it: the text comes
at the end of that tool result, once per session.
Skills are folders with a SKILL.md (name and description in its
frontmatter), found in .claude/skills and .agents/skills of the project and
in ~/.claude-cloak/skills, ~/.config/claude-cloak/skills and
~/.agents/skills. ~/.agents/skills is the open standard's user folder, which
other agents (Pi among them) read too. Claude Code's ~/.claude/skills and Pi's
~/.pi/agent/skills are not read: for a skill Claude Code uses too, keep the
folder in ~/.claude-cloak/skills and link it from ~/.claude/skills. A
project skill wins over a user skill of the same name, and cloak's own user
folders win over ~/.agents/skills. A folder or skill linked from two places
is listed once. The prompt lists each skill in one line.
The agent loads one with its skill tool before it does the task the skill
describes. The tool needs no approval.
A claude pane gets the skills of the .agents/skills folders too (the
project's and ~/.agents/skills), which Claude Code does not read itself.
Cloak links them into the cloak-bridge mod's plugin folder when the pane
starts, and Claude Code lists them as cloak-bridge:<folder>. A skill that
Claude Code already has under the same name (in ~/.claude/skills or the
project's .claude/skills) is left out, so nothing shows twice. A skill added
later reaches the next pane, or a running pane after /reload-plugins. No
request goes out for this: the skills cost only their line in Claude Code's
skill listing.
Customize the prompt
Plain markdown files, no slash commands. The feed starts with one dim line per
file that shaped the system prompt (system prompt: <path> (appended),
instructions: <path>), so nothing is hidden.
SYSTEM.mdreplaces the built-in text: the role, the tool rules and the language rules (short sentences, plain words, active voice, no filler). The working folder, date, OS, the skill list and the instruction files still follow it.APPEND_SYSTEM.mdadds its text after the built-in text (afterSYSTEM.mdwhen both exist).- Each name is looked up on its own, first match wins, no merging: the
project's
.claude-cloak/, the project's.pi/(Pi's folder), then~/.config/claude-cloak/. The project is the git root (else the working folder). A project file beats a user file. Pi's user folder (~/.pi/agent/) is not read: it is written for Pi. AGENTS.override.mdin a folder replaces that folder'sAGENTS.mdandCLAUDE.md(notCLAUDE.local.md, not other folders). It works in~/.config/claude-cloak/and in nested folders too. A blank file counts as absent.
The system prompt is built once when the agent starts and kept, so the prompt cache sees one text. Change a file and start a new session.
Scripting: claude-cloak run
claude-cloak run -m ollama/qwen3 "list the TODOs in src/"
echo "why does the build fail?" | claude-cloak run -m opencode-go/glm-5 --json
claude-cloak run --continue "now fix the first one"
It runs one turn of a native session and exits: no TUI, no daemon, no tty. It
starts its own proxy on a free local port, so every request still goes through
the proxy and nothing extra is sent. Tools run with no approval. The session is
a normal native session file: ^space s s opens it later.
| Flag | Meaning |
|---|---|
-m upstream/model |
the model; required for a new session, else the session's last one |
--continue |
continue the newest native session of the folder |
--session <id> |
continue that session |
--cwd <dir> |
the working folder (default: the current one) |
--json |
one JSON event per line |
-- |
the rest is the prompt |
The prompt is the argument, else stdin. Plain mode prints the final answer on
stdout and the progress (tool calls, errors, the session id) on stderr. Exit
status: 0 on success, 1 when the turn or the run failed, 2 for a bad command
line. The ask tool answers "no interactive user; decide yourself".
--json events (every line has type):
type |
fields |
|---|---|
start |
session, cwd, upstream, model, resume |
context |
files: [{path, role}] that shaped the system prompt (only when there are any) |
thinking, text |
text: a piece of the streamed output |
tool_call |
id, name, input |
tool_result |
id, name, output (what the model got), is_error, status (exit status of bash, when known) |
usage |
input, output, cache_read, cache_write, cost (USD; absent when unpriced), one per response |
error |
message |
end |
ok, session, file (the session file, or null), cost (null when nothing was priced), unpriced (responses with no price), input, output, cache_read, cache_write, error (on failure) |
Files, images and commands in a prompt
@files. Type@in the editor for a fuzzy list of the files under the working folder (.gitignoreis honoured). ↑/↓ choose, Tab or Enter insert the path, Esc closes the list. When you send, the agent adds the contents of every@paththat names a file (cut at 64 KB with a marker) to your message; a folder adds its entries. The feed and the session file show exactly what the model got.- Tab completes a path under the cursor; a second Tab lists the candidates.
- Images. ctrl-v attaches the clipboard's image (
wl-paste, elsexclip), and pasting the path of a PNG, JPEG, GIF or WebP file attaches the file. A chip such as[image 1: 1200×800]shows over the editor; Backspace at the start of the text removes the last one. Images over 5 MB are refused. They are kept next to the session file (<session-id>.d/) and sent in each provider's image format. The feed shows a placeholder line, never base64. When the model list says the model takes no images, cloak says so and sends nothing. readtool. The model reads files with numbered lines,offsetandlimit; an image file comes back as an image.
Setup
List your upstreams in ~/.config/claude-cloak/providers.toml
($XDG_CONFIG_HOME is honoured; CT_PROVIDERS names another file). A bad file
gives no upstreams and the error shows in the status line. Press ^space r
after you edit it.
# A local llama.cpp server (llama-server --port 8080)
[upstream.llama]
format = "openai-chat"
base_url = "http://127.0.0.1:8080/v1"
# Ollama
[upstream.ollama]
format = "openai-chat"
base_url = "http://127.0.0.1:11434/v1"
models = ["qwen3:8b"] # a pin: listed first, always
max_tokens = 4096
# OpenRouter
[upstream.openrouter]
format = "openai-chat"
base_url = "https://openrouter.ai/api/v1"
key_env = "OPENROUTER_API_KEY"
include = ["openai/*", "anthropic/*", "deepseek/*"]
exclude = ["*:free", "*-preview"]
reasoning = "medium"
# DeepSeek
[upstream.deepseek]
format = "openai-chat"
base_url = "https://api.deepseek.com"
key_env = "DEEPSEEK_API_KEY"
# Anthropic, billed to an API key
[upstream.anthropic]
format = "anthropic"
base_url = "https://api.anthropic.com"
key_env = "CLOAK_ANTHROPIC_API_KEY"
max_tokens = 16384
reasoning = 4096
A top-level approval key, before the first table, sets how native panes treat
tool calls: "auto" (the default) runs every call without asking, "ask" asks
first (see Approval below).
approval = "ask"
Each [upstream.<name>] table takes:
| option | meaning |
|---|---|
preset |
a built-in upstream (see Provider presets) that fills in format, base_url, formats and the key sources. A table named like a preset that sets no format uses it too |
format |
the wire format: openai-chat (Chat Completions), openai-responses (Responses) or anthropic (Messages). Required without a preset |
formats |
optional per-model formats: a table of globs on the model id, for example { "grok-*" = "openai-responses" }. A model that matches none uses format |
base_url |
everything the client does not add itself. The client adds /chat/completions, /responses or /v1/messages, so http://host:11434/v1 for Chat and https://api.anthropic.com (no /v1) for Anthropic. Must start with http:// or https://. Required without a preset |
key_env |
the name of the environment variable that holds the API key. Leave it out for a keyless local server |
key_cmd |
a command that prints the key, for a password manager: key_cmd = "pass show openrouter". It runs with sh -c, once per process when the key is first needed, with a 10 s timeout. The output stays in memory: claude-cloak never writes, logs or shows it. A failure shows in the picker as <upstream>: key_cmd failed (exit 1) (or timed out after 10s, no output). key_env, when its variable is set, wins over key_cmd |
enabled |
false hides the upstream, a preset that its key variable would enable included |
models |
optional pins. The picker lists them first under this upstream and always, even when discovery fails or does not return them |
discover |
true by default. false turns discovery off for this upstream: only the pins show |
include |
optional globs (*, ?) on the model id. When set, a discovered model must match one. Pins ignore it |
exclude |
optional globs on the model id. A discovered model that matches one is dropped. Pins ignore it |
max_tokens |
output limit of one response. Anthropic needs one, so it gets 16384 when unset. The other formats send none unless you set it |
reasoning |
"low", "medium", "high" or a token budget such as 4096. Unset: the server's default |
retries |
how often a request that failed for a transient reason is sent again. Unset: the top-level retries, else 5. 0 turns retries off |
A retries = 3 line before the first table sets the default for every upstream.
Provider presets
Common providers are built in. A hosted preset turns on by itself when its key
variable is set; a table of its name with no fields turns on any preset (the
local servers only turn on this way). enabled = false hides one. Fields in
your table always win over the preset's.
| preset | format | base URL | key variable |
|---|---|---|---|
openai |
Chat (*codex*: Responses) |
https://api.openai.com/v1 |
OPENAI_API_KEY |
anthropic |
Messages | https://api.anthropic.com |
CLOAK_ANTHROPIC_API_KEY |
openrouter |
Chat | https://openrouter.ai/api/v1 |
OPENROUTER_API_KEY |
deepseek |
Chat | https://api.deepseek.com |
DEEPSEEK_API_KEY |
groq |
Chat | https://api.groq.com/openai/v1 |
GROQ_API_KEY |
xai |
Chat | https://api.x.ai/v1 |
XAI_API_KEY |
gemini |
Chat (OpenAI-compatible endpoint) | https://generativelanguage.googleapis.com/v1beta/openai |
GEMINI_API_KEY |
mistral |
Chat | https://api.mistral.ai/v1 |
MISTRAL_API_KEY |
cerebras |
Chat | https://api.cerebras.ai/v1 |
CEREBRAS_API_KEY |
together |
Chat | https://api.together.ai/v1 |
TOGETHER_API_KEY |
fireworks |
Chat | https://api.fireworks.ai/inference/v1 |
FIREWORKS_API_KEY |
moonshot |
Chat | https://api.moonshot.ai/v1 |
MOONSHOT_API_KEY |
kimi-coding |
Chat | https://api.kimi.ai/coding/v1 |
KIMI_API_KEY |
minimax |
Chat | https://api.minimax.io/v1 |
MINIMAX_API_KEY |
zai-coding-plan |
Chat | https://api.z.ai/api/coding/paas/v4 |
ZAI_API_KEY |
opencode (Zen) |
per model | https://opencode.ai/zen/v1 |
OPENCODE_API_KEY |
opencode-go |
per model | https://opencode.ai/zen/go/v1 |
OPENCODE_API_KEY |
huggingface |
Chat | https://router.huggingface.co/v1 |
HF_TOKEN |
ollama (opt in) |
Chat | http://127.0.0.1:11434/v1 |
none |
llamacpp (opt in) |
Chat | http://127.0.0.1:8080/v1 |
none |
lmstudio (opt in) |
Chat | http://127.0.0.1:1234/v1 |
none |
[upstream.ollama] # turns the local preset on
[upstream.openrouter] # a bare table also sets the key source
key_cmd = "pass show openrouter"
[upstream.groq]
enabled = false # GROQ_API_KEY is set, but hide it
[upstream.deepseek]
base_url = "http://127.0.0.1:9922/v1" # your field wins
The key comes from key_env, then key_cmd, then the preset's variable, then
claude-cloak login <preset> ($XDG_CONFIG_HOME/claude-cloak/auth.json), then
OpenCode's own auth.json (read only).
Anthropic reads CLOAK_ANTHROPIC_API_KEY only, never ANTHROPIC_API_KEY.
ANTHROPIC_API_KEY is the variable that switches a claude child from your
subscription to API billing. Many shells set it for other tools. If the preset
read it, a native session would bill an API key you never chose. A separate
name makes API billing a decision you made.
OpenCode Go
OpenCode Go is a flat subscription for open coding models. Its terms allow any coding agent that names itself and sends a session id; claude-cloak does both. Add the preset, and nothing else:
[upstream.opencode-go]
It sets the base URL (https://opencode.ai/zen/go/v1) and the formats. The
models sit on three endpoints, so the format is per model: grok-*,
gpt-* and muse-spark-* use Responses, minimax-* and qwen* use Messages,
the rest Chat Completions. Another model on another endpoint? Add a glob (the
file's globs win, the longest glob wins):
[upstream.opencode-go]
formats = { "newmodel-*" = "openai-responses" }
The key comes from the first of these that has one:
- the variable named by
key_env, if you set it OPENCODE_API_KEYclaude-cloak login opencode-go, which asks for the key (nothing shows as you type), checks it with one request and stores it in$XDG_CONFIG_HOME/claude-cloak/auth.json(mode 0600)- OpenCode's own
~/.local/share/opencode/auth.json(read only)
claude-cloak logout opencode-go removes the key that login stored. Without
a key the picker shows opencode-go: no key (run claude-cloak login opencode-go, or set OPENCODE_API_KEY).
The picker's header for the upstream shows your plan's usage
(opencode-go 5h 12% week 3% month 1%) when your account has a Go plan. It
refreshes with the model list.
Model discovery
The picker (^space p, ^space n) lists the models each upstream serves. It
asks the upstream: GET <base_url>/models for the OpenAI formats (with the
key_env key as a bearer token), GET <base_url>/v1/models for Anthropic.
Only models that can call tools show: OpenRouter says so per model, and for the
others the picker drops ids that are plainly not chat models (embedding, tts,
whisper, transcribe, image, dall-e, moderation, rerank). The context size shows
beside a model when the upstream gives it.
- The list is cached in
$XDG_CACHE_HOME/claude-cloak/models.json(~/.cacheby default), so it shows at once after a start or a reload. A start refreshes a list older than three hours in the background. Opening the picker refreshes one older than ten minutes, or one that failed. - A failure shows as one dim row under the upstream (
llama: offline,openrouter: 401 (check OPENROUTER_API_KEY)). The picker still works, and the pins and the last good list stay. - The request goes to the
base_urlonly. It follows no redirect, times out after 10 s and never shows the key. - Type to filter: the picker narrows its rows to those that contain what you
type (case-insensitive, matched on
upstream/model). Backspace edits it. Esc clears it, then closes the picker. Move with the arrow keys orctrl-p/ctrl-n.
The upstream names are also an allowlist: the proxy forwards native requests only to upstreams listed in this file.
Put an Anthropic key in CLOAK_ANTHROPIC_API_KEY, never in
ANTHROPIC_API_KEY. Claude Code switches from your subscription to API
billing when it sees ANTHROPIC_API_KEY. claude-cloak removes that variable
from every claude pane, but a shell that exports it would still bill every
other claude you start. Both variables are also removed from the environment
of commands the agent runs.
Use
-
^space popens the model picker. The native models sit below the Claude Code ones. Pick one to open a native pane in a new tab. -
Enter sends the prompt. While a turn runs, Enter steers: the text goes to the model at the next tool boundary (after the running tool calls, before the next request). If the turn ends first, it runs as the next prompt. Esc aborts the turn and gives the waiting messages back to the editor (see queued messages).
-
shift-Enter or ctrl-j inserts a newline. Shift-Enter needs a terminal that sends it apart from Enter (WezTerm with a binding, kitty). Paste keeps its newlines.
-
ctrl-g edits the prompt in
$VISUAL, else$EDITOR, elsevi. The editor may have arguments (code --wait). Save and quit to bring the text back. If the editor fails, the old text stays. -
Esc aborts the running turn and kills its command. It does nothing when the agent is idle.
-
Approval. Every tool call runs without asking. Set
approval = "ask"inproviders.tomlto be asked:bashthen asks before every command and the box shows it.yruns it,aruns it and stops asking for the rest of the session, any other key denies it, and the model sees the denial.edit,writeandmulti_editrun without asking inside the working folder and ask once when any path is outside it. The status line readsaskin that mode. A pane that died, or that you closed, starts again with the mode it had. Any other new or resumed pane takes the configured mode. Inaskmodeweb_searchandweb_fetchask too: they send text off the machine. -
Web. The model loads the
webskill to getweb_search(titles, URLs and excerpts) andweb_fetch(a page's main text as markdown, in parts for a long page). Search uses Exa's free endpoint and needs no key. Choose another in a[web]table ofproviders.toml:[web] search = "searxng" # "exa" (default), "searxng", "degoog", "brave", "deepseek" or "off" url = "http://127.0.0.1:8888" # the SearXNG instance (JSON output on), or a list # key_env = "BRAVE_API_KEY" # Brave's key (DeepSeek's: DEEPSEEK_API_KEY); Exa's optional one is EXA_API_KEY # fallback = "exa" # "exa", "brave" or "deepseek": search here when the first gives no result # fetch = false # turn web_fetch off # private = true # let web_fetch read this machine and the LANA self-hosted degoog needs no
urlon its default port (4444). Its server settingsearxApiEnabledadds page dates. When degoog wants an API key, name its variable inkey_env. Withfallback = "exa", Exa searches when degoog is down or finds nothing, and the result says so. Without a fallback, a query goes only to the backend you named.search = "deepseek"uses DeepSeek's Search API with your DeepSeek API key:DEEPSEEK_API_KEY, else the key ofclaude-cloak login deepseek. It costs $0.75 per 1,000 searches that find something, and takes 5 searches a second and queries of at most 128 characters.For an instance you reach at home and away, list both addresses: each is tried in order, and an address that does not connect in 2 s is skipped.
[web] search = "degoog" url = ["http://192.168.1.10:4444", "https://search.example.com"] pangolin_token_env = "DEGOOG_PANGOLIN_TOKEN" # behind Pangolin's login fallback = "exa"pangolin_token_envnames the variable that holds a Pangolin shareable link's access token,<id>.<token>(itsp_token). It goes to https addresses only. Thekey_envkey goes to every address, plain http too.web_fetchrefuses addresses on this machine and the local network unlessprivate = true. It reads HTML and text, not PDFs or images. -
Questions. The model can ask you with the
asktool: one to four questions, each with 2 to 6 options and a short header. It never needs approval, and while it waits the tab turns yellow and you get the usual notifications. The question panel takes the place of the editor (up to 60% of the screen; the feed stays above, the text you were typing stays under it). The model may mark its pick with(Recommended)and show a monospace preview beside an option.- Tab, shift-Tab, ←, → move between the question tabs and the last tab, Submit. A tab with an answer shows a check mark. A single choice moves you to the next tab.
- ↑/↓ highlight an option. Enter picks it (single choice) or toggles it (several). Space toggles too. 1 to 9 pick or toggle that option at once.
- Type on a highlighted option to add a note to it. The note shows under the option, Enter picks the option with the note, Backspace edits it and Esc drops it. Once a note has begun, digits are text.
- The last row, Other, is free text: what you type there is the answer.
- ctrl-g opens the note, the Other text or the overall note in
$VISUAL/$EDITOR. PageUp/PageDown scroll a long preview. - Submit lists every answer. Type an overall note there and press Enter to send. Left-open questions read as unanswered, after one confirmation line.
- Esc with no note to drop asks
dismiss the questions? y/n. y tells the model you declined. A hot reload keeps the questions and what you typed. The block in the feed shows the questions, and your answers highlighted.
-
The tab title is your first prompt. The usual tab glyphs, unread blink and notifications work for a native pane.
-
No slash commands. A prompt that starts with
/is plain text for the model. The pane's actions are prefix keys:^space s t(tree),^space s h(handoff) and^space m(model). In aclaudepane or with no pane they say so in the status line. -
^space s tshows the session as a tree of your prompts and the final answer of each turn, with branch lines, the current path bright and the current point marked◀ here. Up and down move, left folds a node (or goes to its parent), right unfolds (or goes to its first child), and typing filters by text. Enter on an answer continues from it with your next prompt. Enter on a prompt puts its text in the editor, so you can edit it and send it as a new branch. The old branch stays in the file, and nothing is summarised. The feed gets a⑂ branch at <time>rule and the new path, and the switch sends no request. It needs an idle agent.^space s sshows the branch count of a session. -
Resume.
^space s slists native sessions next to Claude Code ones, taggednative <upstream>/<model>. Enter resumes one on the upstream and model it was started with, and the turn tree andbbranching work as for any session. A resume continues from the point the tree left it at. The upstream must still be inproviders.toml. A pane that died or that you closed starts again as a native pane, resuming its session if it wrote one, else as a fresh native session on the same upstream and model. Session files are in~/.local/share/claude-cloak/sessions/.
The session list
^space s s lists the live sessions, then the native sessions, then the Claude
Code transcripts, each group newest first. A native team agent's session is not
a row of its own: its session's row counts it (⑂2).
The list opens with the cursor in its find field. Type to filter the past
sessions by title, name, id, model and, for a native session, the text of its
messages. Several words must all match. ↑/↓ (or ctrl-p/ctrl-n) walk,
enter opens, ctrl-u clears the field, esc clears it and closes the list
when it is empty. Tab keeps the filter and gives the keys to the list, where
j/k walk and these keys work; Tab or / go back to the field:
| key | does |
|---|---|
r |
rename the highlighted session (also a live one). An empty name clears it |
d |
a native session: ask, then move its file to the trash. A Claude Code session: hide it from this list |
u |
show a hidden session again (the highlighted one, else the one you hid last) |
n |
only named sessions |
H |
show the hidden sessions too (marked hidden) |
A native session's name is an entry in its own file. A Claude Code session's
name and its hidden mark live in $XDG_STATE_HOME/claude-cloak/session-names.json
(~/.local/state by default); claude-cloak never writes to Claude Code's
transcripts, and it never deletes one. A deleted native session moves to
$XDG_DATA_HOME/claude-cloak/trash/<project>/<id>.jsonl; move the file back
into sessions/<project>/ to restore it. A live session cannot be deleted or
hidden: close its pane first. The filter shapes the past sessions; live ones
always show.
^space y copies the last answer of the active pane to the clipboard (OSC 52,
and wl-copy when WAYLAND_DISPLAY is set).
Queued messages
While a turn runs, Enter steers: the agent gets the text after the next
tool call. The waiting messages show above the editor, one dim row each (three
rows at most, then +N more). The status line counts them.
Up, with the cursor on the editor's first row, takes the waiting messages back into the editor. They go before your draft, separated by blank lines. The turn goes on. If the messages already went to the agent, the status line says so.
Esc aborts the turn and gives the waiting messages back the same way. Nothing of them reached the model.
A claude pane shows its queue too: the messages you sent with Enter while
Claude Code's turn runs show as the same dim rows over its input box (compact
view). Cloak reads them from the session's transcript, so a row shows within
about a second. Up in the pane works as Claude Code does it, and the rows go
away with the messages.
Effort (^space s e)
^space s e opens a list of the effort levels the pane's model takes (off,
low, medium, high, …), with the pane's own level marked. ↑/↓ move,
enter or a digit picks, Esc closes. In a claude pane the list starts with
auto (the session's own level), and the pick goes through the pane's mod. The
level shows in the status line and on the pane's border, takes effect with the
next request (also inside a running turn) and is
saved in the session file, so a resume keeps it. A new session starts at the
upstream's reasoning from providers.toml, shown as that level (default
when the upstream sets none, 4096 tokens for a budget).
| Format | off | low / medium / high |
|---|---|---|
| Anthropic | no thinking | thinking on: an effort for models that take one, else a budget of 1024 / 8000 / 24000 tokens (max_tokens rises to 32000 for high when you set none) |
| Chat Completions | reasoning_effort: "none" ("minimal" for GPT-5 before 5.1) |
reasoning_effort |
| Responses | reasoning.effort: "none" ("minimal" for GPT-5 before 5.1) |
reasoning.effort |
The list offers the levels the model takes, judged by its name. OpenAI's o1,
o3 and o4 models have no off. DeepSeek's reasoner and R1, QwQ and
-thinking models think whatever you ask: the status says effort: fixed and
the key opens no list. For a model the list does not know, all four levels are
offered, and the provider's error tells you when one fails.
Retries
A request that fails for a reason that can pass is sent again, up to retries
times (5 unless providers.toml says otherwise, per upstream or at the top).
The wait is the server's retry-after / retry-after-ms when it sends one,
else 2, 4, 8, 16, 32 seconds with some jitter. A server that asks for more than
two minutes fails the turn at once.
- Retried: HTTP 408, 409, 429, 500, 502, 503, 504 and 529, a connection that broke, a stream cut before its end and an overload error inside a stream. If an answer was already streaming, it is dropped and the feed says so.
- Not retried: 400, 401, 403, 404, a full context window, a spent quota or balance, and any other error event. They stop the turn with the server's text.
- Every retry is a real request through the proxy, so the feed shows it. The
wait shows in the status line and as a dim line in the feed (
retrying in 8 s (attempt 3/5): HTTP 529: Overloaded). Esc cancels the wait and ends the turn. Agents of the team retry the same way.
Handoff (^space s h)
There is no compaction. ^space s h starts a new session that carries only what
you pick. It opens a model picker first (native models, your current one
preselected). Then:
- claude-cloak reads the facts from the session file and git: your prompts,
the files changed with their
+/−counts, the commands run and the last test or build result,git status --shortand the branch. No model is used. - One request on the model you picked reads a compact transcript (prompts, answers, tool calls with cut arguments, no tool output) and proposes decisions, learned facts, open tasks and constraints. It shows in the feed like any request. Over about 60k tokens the oldest tool-call arguments are cut first, and a note says so. If it fails you still get the facts.
- A question panel lists each group (up to 20 items) and the facts, which start selected. Type a note on any item, use the Other row, add an overall note on Submit.
- The result is a markdown document in the editor. ctrl-g edits it, Enter accepts it, Esc cancels with nothing changed.
- The new session replaces the pane's agent, in the same tab. The document is
its first message, under a rule in the feed, and its file records the old
session as
parent. The old session stays in^space s s.
A session with a parent has the recall tool: it searches the old session
(prompts, answers, tool calls and outputs) by text or regex, or reads one turn
in full, and reads no other session. No approval is asked.
Switching models, context and cost
^space mopens the model picker with native models only (your current one preselected); type to filter. The pick switches the pane at once. The next request uses the new model. While a turn runs the switch is refused (the status line says so): abort the turn first. The feed gets a dim rulemodel → upstream/model, the tree marks the answer where the model changed, and a resumed session continues on the last model it used.- The history converts. A message keeps its text, its tool calls and its
results across Anthropic, Chat Completions and Responses. What only the writing
provider can check (Anthropic's thinking signatures, Responses' encrypted
reasoning, OpenRouter's
reasoning_details) goes back only to the same upstream and model, and is dropped for any other. - The status line shows
ctx 45k/200k: the tokens of the last request (input with cache reads and writes, plus output) against the model's window. It is dim below 60%, yellow above 80% and red above 95%. Without a known window it shows the tokens only. - Cost shows next to it (
$0.42) and at the end of each response rule. OpenRouter reports the cost in the stream, and it is used as it comes. For other upstreams the price comes from the models list when it has one (OpenRouter'spricing, with cache rates). With no price, nothing shows: claude-cloak never guesses. A+after the sum ($0.42+) means some responses had no price. The sum covers the whole session across model switches, and a resumed session shows its total from the file.
What the feed shows
Your prompts, the model's thinking and text, and a block per tool call. A
bash call streams its output live and ends with [exit status: N]. The model
sees at most 30 KB and 300 lines of it (the first 250 and the last 50); past
that a marker names a temp file that holds the whole output. An edit or a
write shows its diff, and a multi_edit shows one diff for all its files. So does a
bash command that changes files in a git work tree:
claude-cloak snapshots the tree before and after with a temporary index and
diffs the two. Your real index, branch and files are never touched, and the
model sees only what the command printed. A past session shows the same diffs,
read from its file.
The agent has four tools that change files. bash runs commands. edit changes
one file by exact text replacement. write creates a file or replaces all of one;
it replaces an existing file only when the agent read all of it with read in
the session and the file did not change since, so a guess cannot wipe a file.
multi_edit applies a list of edits, in many files, as one atomic call: if one
edit fails, no file is changed. The agent reads AGENTS.md
and CLAUDE.md from the git root and the working folder into its prompt.
Agents
The agent can start other agents. Four tools, no more: agent_start (a name, a
prompt, optionally a model upstream/model, context: "fork" to copy the
conversation so far, and worktree: true for a git worktree on a new branch
next to the repository), agent_send (a message to an agent or to main),
agent_stop and agent_list. Only the main agent starts and stops agents, and
agents cannot start agents.
- An agent works in the background with its own history and its own session
file. Several
agent_startcalls in one reply run in parallel. At most four run at once; more wait. - When an agent finishes, its answer goes to the main agent at its next tool boundary, or wakes it if it is idle. A message to an idle agent wakes it, so that is how you ask a finished agent for more.
- Each agent has its own stream:
^space s alists them. While an agent's stream shows, Enter sends it a message as you. The status line says who gets it. - An agent's
askshows in the main pane's question panel with the agent's name. Several questions wait in a queue. - Esc stops the main turn. A second Esc stops every agent.
- Limits: 75 requests per agent until you or the main agent write to it again,
20 messages per agent per main turn. Agents need
approval = "auto"(the default). A worktree agent's answer names its branch; nothing is merged or removed for you.
Native agents a claude pane calls (^space c n)
A claude pane can use cloak's native agents: other models, on your
providers.toml models, each with its own history and tools, working in the
same folder. Claude Code gets the same team tools a native pane's main agent
has, so the work costs the Claude Code session's context nothing.
It is off for every session until you turn it on: ^space c n opens the
picker on the active claude pane.
┌ native agents · on · 1 model ────────────────────────┐
│ ❯ type to filter │
│ deepseek │
│ [ ] deepseek/deepseek-flash 1048.6k │
│ fake │
│ [x] fake/fake-text │
└─────────────── ↑↓ move · space check · ctrl-a/x bump ┘
- Type to filter,
spacechecks the highlighted model: the session's agents may run on the checked ones. No model checked is off, and off adds nothing to the session's requests. Esc closes and keeps what you set. - The setting belongs to the Claude Code session (its id), kept in
prefs.jsonnext to the leaderboard's default, so a resume keeps it. A/clear, a/resumeor^space s tin the same pane takes it along. - The tools join every request of the session, with the list of models. Turning it on or changing the models mid-session makes the next request write the session's prompt cache again once; the status line says so.
The tools your Claude model gets (Claude Code shows them as
mcp__cloak-bridge__agent_start and so on):
| tool | what it does |
|---|---|
agent_start |
start an agent by name, with a prompt, tools (reads, writes or a list), an effort (low to max), optionally a model you checked (else cloak picks one) and a worktree |
agent_send |
a message to an agent by name: a running one reads it at its next tool boundary, a finished one wakes up with its own history |
agent_list |
the agents, their state and model, the tool call each runs now, and the start of its latest text |
agent_read |
an agent's latest steps from its own history (its text, thinking, tool calls and results), at no cost to the agent |
agent_stop |
stop an agent's running turn; it keeps its history |
agent_rate |
score a finished run (correct, complete, focused, 1 to 5); cloak's model pick reads the ratings |
- Every call returns at once. The agents work in the background.
- When an agent finishes, or sends
maina message, it reaches Claude as Claude Code's own background agents do: inside the running turn, or as a new turn when Claude is idle. That turn is the one thing the mod starts on its own, and only in a session where you turned the agents on. - Each agent has its own stream in the feed:
^space s alists them in the native colour, with their live output and the time of each command. - Agents are addressed by name. A resumed session gets its agents back, idle until a message wakes them.
- An Esc in the pane does not stop the agents. Closing the pane,
/clearand a session end do. A hot reload (^space r) keeps them working.
The agents run with no approval prompts, so a writes agent edits files
directly. An agent's ask gets "nobody can answer here": it decides itself or
says so in its answer. Each agent writes its own session file, which ^space s s
lists. The limits of the native team apply: at most four agents run at once,
75 requests per agent until Claude writes to it again, 20 messages per agent
per turn of Claude's.
Limits
- No compaction. When the context window is full, the turn stops with an error. Start a new session.
- No MCP, and no tools beyond
bash,read,edit,write,multi_editand the agent tools. - No sandbox.
bashruns with your rights in the working folder, and by default nothing asks first. Setapproval = "ask"if you want to read each command before it runs. - Anthropic, DeepSeek, OpenRouter and local servers differ in what they accept. An error from the server shows in the feed and the next prompt works.
Display
- ✻ thinking — dim italic, streamed token-by-token
- text — rendered as markdown (
tui-markdown) - ⚙ tool calls — input JSON pretty-printed on completion, raw fragments while streaming
- meta — message boundaries with model, context size, stop reason, token counts
- errors — API/stream errors in red
Sessions are keyed by the Claude Code session ID found in request metadata; concurrent requests (subagents) tap independently.
Leaderboard (^space l b)
The bottom rows of the feed can show the session's most-edited files:
├── most edited · 7 files ─────────────────────── +201 -47 ──┤
│ 1 src/ui.rs ×9 +142 -38 │
│ 2 src/keymap.rs ×3 +24 -3 │
│ 3 .claude/skills/feed-ui/SKILL.md ×1 +12 -1 │
└────────────────────────────────────────────────────────────┘
×9is how many calls changed the file.+142 -38are the lines they added and removed. The rule shows the file count and the totals over all files.- The most lines changed rank first, then the most edits.
- It counts every lane of the session, subagents too:
Edit,WriteandMultiEdit, the nativeedit,writeandmulti_edit, and the files a Bash call changed. A call that was denied or failed changed nothing. ^space l bopens a pop-up withoff,3 files,5 filesand10 files.↑/↓change the leaderboard at once,enterorEscclose.ctrl+ssaves the row as the default for new instances (in$XDG_STATE_HOME/claude-cloak/prefs.json,CT_PREFSnames another file). The setting belongs to the instance: a hot reload keeps it.- It shows after the first edit. In a short feed it gives up its rows first, so the feed keeps at least 4 rows.
lazygit (^space l g)
^space l g runs lazygit in a box
over most of the screen, in the folder the instance runs in, like a floating
terminal in an editor.
- Every key goes to lazygit,
Escandctrl+dtoo. The mouse works inside the box. qquits lazygit and closes the box.^space l gagain hides the box and lazygit keeps running. The next^space l gshows it as you left it. Any other^spaceaction hides it too.- A hot reload keeps it.
- lazygit is not bundled. When
lazygitis not on$PATH, the key opens nothing and the status line says where to get it. When lazygit fails to start, the status line shows its error.
--headless runs the proxy without the TUI (and without the daemon). CT_PORT overrides the port (default 8484). CT_PROVIDERS names the providers.toml file for native sessions.
Hot reload
Swap a running instance onto a newly built binary with ^space r — without
losing the proxy port, the embedded claude pane, or the live feed.
cargo build # in any terminal, whenever you like
# then press ^space r in each running instance
claude-cloak never builds anything itself and watches no files. You rebuild the way you always would; the key says "run that one now".
It execs the same path the instance was started from, so a debug instance reloads onto a rebuilt debug binary and a release instance onto a rebuilt release one. It does not cross profiles.
How it survives
The app execves the new binary into its own process, so the pid, the open
file descriptors and the child processes all stay. Before the exec the proxy
drains: it stops accepting and lets in-flight responses finish, while the
listening socket stays open so requests made during the swap wait in the kernel
backlog and are served by the new code. Nothing is refused and nothing is
truncated.
The footer shows ⟳ reloading… while it drains, then · reload #1 once the new
code is running. A failed exec — pressed while the linker still had the file
open — reports ⚠ reload failed: … and changes nothing; press it again.
A state snapshot the new types no longer fit costs the feed only — never the port and never the pane.