f float

A persistent brain for Claude Code.

Your AI pair-programmer has amnesia. Float is the cure — a local daemon that remembers tasks, caches HTTP, pre-indexes your repos, and shrinks LLM prose to a fraction of its token cost.

Download detecting your platform… All platforms

latest: loading… macOS arm64 · Linux amd64 · Linux arm64

Downloads

All artifacts are mirrored to Cloudflare R2 at float-release.benehiko.com. Each tarball ships with a .sha256 sidecar — verify before extracting.

Windows

not yet supported

Float embeds a Linux daemon image and signs Mach-O binaries on macOS for virtualization entitlements. Windows support is on the roadmap.

Verify a download 
# macOS / Linux
shasum -a 256 -c float-vX.Y.Z-<platform>.tar.gz.sha256

# extract
tar -xzf float-vX.Y.Z-<platform>.tar.gz

# install (copies to ~/.float/bin/ and starts the daemon)
./float install

What is float?

A sidecar daemon that gives Claude Code the long-term memory and offline intelligence it doesn't ship with.

Remembers

Tasks, decisions, blockers, and outcomes survive across sessions in a local SQLite store. Resume work without re-explaining yesterday.

Caches

A forward HTTP/HTTPS proxy with TLS interception caches every cacheable response. Repeat hits to docs, GitHub, and APIs come straight from disk.

Indexes

Git history, file trees, and source code are pre-indexed in the background. Semantic search over commits and code chunks via MCP tools.

Compresses

The optional claude-lang mode swaps common English words for single CJK glyphs on the wire — roughly 75% fewer output tokens — and decodes back to plain English before you read it.

Observes

A live dashboard at https://localhost:7680/dashboard/ and a TUI (float watch) show indexing progress, proxy traffic, hook events, and resource use.

How it works

Claude Code ──stdio──▸ MCP Bridge ──HTTPS──▸ floatd
                                               ├── Task Memory    (SQLite + sqlite-vec)
                                               ├── Git Intel      (background watcher)
                                               ├── Code Search    (semantic, chunked)
                                               ├── File Tree      (cached dir structures)
                                               ├── Token Tracker  (per-session analytics)
                                               ├── Proxy          (HTTPS MITM, response cache, blocklists)
                                               └── Dashboard      (Go templates + htmx)

HTTPS_PROXY clients ──HTTP CONNECT──▸ floatd :7681 (TLS intercept, DNS via Quad9)
  1. floatd is the daemon. It runs on 127.0.0.1:7680 for the API and :7681 for the proxy. TLS certificates are generated on first start.
  2. The MCP bridge is a stdio shim that Claude Code spawns. It speaks JSON-RPC to the model and HTTPS to floatd, exposing tools like task_log, code_search, and git_history.
  3. Hooks inject context at SessionStart, intercept Grep/Glob/find/ls and bash git/gh calls (suggesting pre-indexed alternatives), and record tool-call analytics.
  4. The proxy is opt-in. When enabled, Claude Code's outbound HTTP traffic flows through floatd, where cacheable responses are stored in SQLite and curated blocklists drop malware/ad/tracker domains.

Install

Prerequisites: a container runtime (docker or nerdctl) and the claude CLI on your $PATH.

  1. 1. Download & extract

    Grab the tarball for your OS from the downloads section and extract it.

    tar -xzf float-vX.Y.Z-darwin-arm64.tar.gz

  2. 2. Run ./float install

    The binary installs itself into ~/.float/bin/, starts the daemon, waits for it to report healthy, and registers the Claude Code plugin.

    ./float install

    The installer aborts before touching ~/.claude/settings.json if the daemon fails to start, so your Claude config never points at a dead service.

  3. 3. Restart Claude Code

    Float wires up MCP tools and hooks automatically. Restart the editor so it picks up the new settings.json.

Upgrade

Replace the binary, then refresh the daemon image.

# 1. Download the new tarball (see Downloads) and extract
tar -xzf float-vX.Y.Z-<platform>.tar.gz

# 2. Re-run install — copies the new binary to ~/.float/bin/,
#    refreshes the embedded daemon image, and recreates the
#    floatd container in place.
./float install

# 3. Verify
float version
float status

Float embeds the linux daemon OCI tar into the binary at release time, so a binary upgrade also upgrades the daemon image. The install step recreates the running container so it picks up the new image.

The proxy

A forward HTTP/HTTPS proxy with TLS intercept, response caching, and blocklists. Off by default.

Why turn it on

  • Cache. Documentation pages, GitHub responses, and API payloads come from local SQLite on the second hit — no extra network round-trip, no rate limits.
  • Filter. DNS resolves through Quad9; curated blocklists (StevenBlack, URLhaus, Hagezi) drop known malware, phishing, and tracker domains before the request leaves the host.
  • Observe. Every request is recorded to the dashboard with cache-hit, block, and latency markers — see exactly what your AI is fetching.

Why leave it off

  • Corporate networks with their own MITM proxy.
  • Debugging external APIs that misbehave under TLS interception.
  • You'd rather not trust an extra CA in your shell environment.

Enable

float proxy enable      # writes HTTPS_PROXY / HTTP_PROXY / NODE_EXTRA_CA_CERTS
                        # into ~/.claude/settings.json
# restart Claude Code so it re-reads settings.json
float proxy status      # confirm listener is reachable

If you already have HTTPS_PROXY set (corporate proxy, mitmproxy), float proxy enable refuses to overwrite it. Clear the existing value first.

Disable

float proxy disable     # removes the entries from ~/.claude/settings.json
# restart Claude Code

Point any other client at it

export HTTPS_PROXY=http://127.0.0.1:7681
export HTTP_PROXY=http://127.0.0.1:7681

# Trust the float CA so intercepted TLS connections validate
curl -sk https://127.0.0.1:7680/api/v1/proxy/ca.crt > ~/.float/data/certs/ca.pem
export NODE_EXTRA_CA_CERTS=~/.float/data/certs/ca.pem

Token reduction

Two layers: cache the network, compress the prose.

Layer 1 — Cache the network

The proxy turns "Claude fetches the same 50 KB documentation page six times a day" into "Claude fetches it once, the next five reads come from a local SQLite blob in milliseconds". You don't pay for the bytes again and the model doesn't burn input tokens parsing a slightly different copy of the same page.

Layer 2 — Compress the prose

Float embeds claude-lang, a tiny lossless transpiler that swaps common English words for single CJK glyphs. The model emits 丯ing 三 〔file〕 on the wire (one token each) and a decoder restores building to file before the user reads it.

The hot table covers articles, conjunctions, prepositions, modal verbs, and the most common nouns/verbs in dev prose — roughly 75% of the word-count of a typical assistant reply. Code blocks, file paths, and identifiers are wrapped in literal escapes so they pass through unchanged.

It's opt-out. Toggle with float cl disable / float cl enable if the extra MCP round-trip hurts latency more than the token cost helps.

Bonus — Pre-indexed search

Hooks intercept Claude's Grep / Glob / find / ls calls and suggest pre-indexed alternatives backed by local embeddings. Same answers, fewer tool round-trips, far fewer tokens spent reading directory listings.

Releases

Every tagged release is mirrored to R2 with sha256 sidecars and a changelog generated from commit history.

Loading release history…

Raw artifacts available at float-release.benehiko.com/releases/.