Set it up. Understand how it works.

Install

One command finds your OS. On Linux and macOS. On Windows get the installer from Releases.

Quick start

1. 1
   Get Cinderpaw. Open it. Complete onboarding and name your agent.
2. 2
   Get a model. For local inference, browse Models and download a model that fits your hardware. For cloud inference, add your API key in Settings → Cloud Keys. Keys are stored locally and sent to the selected provider for authentication.
3. 3
   Chat. Or flip to Agent mode. Agent mode enables the sidecar for tool use, persistent memory, file operations and web research.

Like the terminal? cinderpaw chat opens a full screen chat. Same chats. Same recall. Same models. cinderpaw setup runs the guide. And cinderpaw gateway runs it in the back.

What's inside

Architecture

One repo. Four parts. Three ways they talk. You came to copy it and read the code. This part and the next two are the map. They match ARCHITECTURE.md in the repo. That file is updated first.

┌───────────────────────────┐   ┌───────────────────────────┐
│  Desktop UI (React/Vite)  │   │  TUI (Go + Bubble Tea)    │
└─────────────┬─────────────┘   └─────────────┬─────────────┘
              │ Tauri IPC                     │ HTTP
┌─────────────┴───────────────────────────────┴─────────────┐
│  Rust host - crates/cinderpaw-core                            │
│  ├── desktop: src-tauri/      ├── headless: cinderpaw-cli/    │
│  ├── llama.cpp answering engine       (:11435)           │
│  └── OpenAI / Ollama-compatible HTTP API + bearer token   │
└─────────────────────────────┬─────────────────────────────┘
                              │ JSON-lines on stdout
┌─────────────────────────────┴─────────────────────────────┐
│  Sidecar - CinderpawAgent/  (Bun + TypeScript, one binary)    │
│  └── helper loop · BRSI engine · recall · tools · sandbox  │
└───────────────────────────────────────────────────────────┘

The four parts

Five rows. Four parts. The desktop shell and the headless gateway are two hosts of the same cinderpaw-core crate.

The three ways they talk

Provider credentials are injected by the Rust host. The desktop host adds stored credentials when configuring the sidecar. Audit that boundary starting at cinderpaw_set_model.

Layer map (L0-L6)

The BRSI stack is true code. Not just an idea. Each step owns a part of the tree. Hard deals rule them. One rule will bounce your PR. Respect layer boundaries. All talk goes through rsi/sidecar.ts, rsi/engine.ts and rsi/mod.ts. Paths below start at CinderpawAgent/src/ unless they say more.

Full file list lives at CinderpawAgent/src/rsi/README.md. Safety deals live in docs/invariants.md. Big ideas live in docs/brsi-spec.md.

Where do I add X

Each new helper asks one of these in the first hour. So here they are first.

If you add a file under rsi/ update the step list in ARCHITECTURE.md and rsi/README.md in the same PR. Old docs count as a true bug. The next reader will trust the wrong thing. Human or helper.

Agent runtime

Flip the switch to Agent mode. Your words go to the Bun and TypeScript sidecar. It recalls good recall. It sends words live. It loops tool calls till it has an answer. Up to 10 loops per note. 50 for hard long jobs like deep research.

user message
    │
    ▼
[Recall]    adds good old recall (FTS5 and saved facts)
    │
    ▼
[Answering] sends words live to screen
    │
    ├── tool call?  → execute → feed result back → loop
    └── no tool call → final answer, save to recall, done

Tired web tools try again. They wait a bit more each time. They move down the web_search → deep_research → read_webpage chain.

Memory layers

Cinderpaw keeps lots of kinds of recall. They stay past each chat. From a word log you can search. Up to a smart tree that gets what you truly said.

Fractal Memory uses a RAPTOR-style tree. Raw events form the leaves; k-means groups related events and the model summarizes each cluster. Retrieval traverses this hierarchy to find the idea of old work. Not just same word matches. SQLite and FTS5 provide a keyword fallback, so keyword retrieval remains available before the summary tree is built.

Privacy tags. Wrap sensitive text in <private>…</private>. It is excluded from memory persistence. The model still receives it for the current turn, including a cloud provider if selected.

Self-improvement (BRSI)

The adaptation system is called BRSI: Bounded Recursive Self-Improvement, six adaptation layers above the L0 substrate. Candidates compete against the current champion under evaluation and promotion policies. The system records changes and supports rollback. A passing evaluation is evidence for that test, not universal improvement.

Bounded by policy. Activation and approval depend on the layer. Deeper layers are disabled by default; meta-evolution requires human approval. The scorer and fixed policy bounds sit outside the mutable scope.

Built-in tools

A small taste of the built in tools. Persona and chat builds add more. Like capture_lead and schedule_meeting. And with tool_forge the helper writes its own tools too. So the list never ends. Each tool states its needs at sign up. No state means no run. Web calls go through a safe gate. With SSRF guard and speed cap and a log. File tools heed a hard no list on ~/.cinderpaw and ~/.ssh.

Privacy, honestly

• Local models. Local inference runs on your computer, with local memory storage. Network tools, connectors and update checks are separate. The installer sends a one-time version/OS count unless you opt out on the last setup screen.
• Cloud models (BYOK). The desktop runtime calls your selected provider directly. Prompts and selected context leave your computer when cloud inference runs, including agent or background tasks using that model. Your key authenticates those requests.
• Web tools. Tools such as web_search and deep_research make network requests through an egress gateway with SSRF checks, rate limits and logging.
• Update check. Once per start Cinderpaw asks GitHub Releases if a new build is out. Just the build ask. No use data. Turn it off in Settings then General for a fully offline app.

Environment variables

The sidecar reads these settings. Configure filesystem access and tool permissions for your workload. The full list is in the README.

License

One license for everything: Apache-2.0. The desktop app, the TUI, the agent runtime and the smart core. The full text lives in the repo LICENSE file.

• ✅ Free for all. Home use. Work use. Big firms too. Self host. Changed. Shared. Even as a hosted serve.
• ✅ No legal review needed. Apache-2.0 is an OSI license most companies already allow.
• 🕓 It used to be BSL 1.1. That changed in September 2026, so older pages or posts may still say BSL.