Docs

Set it up. Understand how it works.

Install the alpha, choose a model and give it a task. This guide covers the runtime, memory, tools and boundaries around self-improvement. Start with a workspace you can safely test in.

Follow the setup below, or jump to Architecture to inspect the implementation. For the latest details, check the repo, which is updated first.

Install

Cinderpaw comes two ways. The desktop app is a normal app you download. It can run models on your own computer or in the cloud. The Browser App installs with one line and opens in your browser. It works with cloud models only.

Desktop app

Download the file for your computer and open it.

On a Mac or Linux, this line installs the desktop app from Terminal:

The app is not signed yet, so your computer may warn you the first time. On Windows, click More info → Run anyway. On a Mac, if it says the app is damaged or can't be opened, run xattr -cr /Applications/Cinderpaw.app in Terminal once, then open it again.

Windows signing is on its way: free code signing provided by SignPath.io, certificate by SignPath Foundation. See the code signing policy.

Browser App (one line)

Mac and Linux, in Terminal:

Windows 10 or 11, in PowerShell:

It puts Cinderpaw in one folder, ~/.cinderpaw, and opens it in your browser. No admin password. Run the same line again to update. It has no engine for models on your own computer: for that, get the desktop app above. Step by step help is at cinderpaw.dev/app. On a Linux server you can build it from source instead: add -s -- --from-source.

Just the CLI (npm)

The npm package provides the terminal agent with cloud inference. It has no local llama.cpp engine in it. For local GGUF models get the desktop app above.

Quick start

  1. 1
    Get Cinderpaw. Open it. Complete onboarding and name your agent.
  2. 2
    Get a model. Easiest: press Sign in with OpenRouter. Or paste an API key in Models → Cloud. For a model on your own computer, open Models → Hugging Face and pick one that fits your hardware. Keys are stored locally and sent only to the provider you picked.
  3. 3
    Ask for something. Every message goes to the agent: it uses tools, remembers you, works with your files and searches the web. There is no mode to switch.

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

Chat

Talk to your helper with a local or cloud model. Organize conversations into projects.

The agent

Every message goes to a TypeScript agent with tool use, persistent memory and an execution loop. No mode to switch.

Memory Layers

Working context, searchable history, durable facts and hierarchical summaries for retrieval across sessions.

Self-forging tools

Generate, update and retire tools at runtime through tool_forge, with checks, permissions and logging.

Self-Improvement (BRSI)

Evaluate changes to configuration, adapters, tools and code through bounded promotion policies. See Self-improvement below.

Connectors

Talk to your helper from 21 chat apps, like WhatsApp (QR pair), Discord, Slack, Telegram and Signal. Same configured model and local memory.

Deep Research

Search the web, read sources and produce a cited Markdown report.

Local Models

Load and unload GGUF models from disk, with active-model status and hardware suitability estimates.

Model Fitness Scoring

Local models receive a 0–100 suitability score based on hardware fit, speed and context capacity.

Browse HuggingFace

Find and download models from Hugging Face inside the app.

SkillHub

Add and find skills that grow what the AI can do.

Cloud models (BYOK)

Sign in with OpenRouter, or bring your own key for 35 cloud providers in Models → Cloud, like OpenAI, Anthropic, Gemini, DeepSeek, Groq, Mistral, OpenRouter, Kimi, GLM and MiniMax, or a compatible custom endpoint.

Privacy Tags

Wrap words in <private>…</private> and they never touch the recall base.

Tool Health Monitor

Per tool win rates and speed tracking. The agent can identify unreliable tools.

Workspace Scanner

Finds hidden passwords and bad code bits in the workspace. Before you send them to GitHub.

Hardware Monitor

GPU, VRAM and RAM readings, plus Vulkan availability checks.

Auto-updater

Background checks for available updates, with minisign verification.

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

PartBuilt withDoes
Desktop UIfrontend-react/React + Vite + ZustandRendering, chat surfaces, the mascot, settings UX.
Rust host (desktop)src-tauri/ + crates/cinderpaw-core/Tauri 2 + llama.cppIPC, filesystem, GGUF answering, the 127.0.0.1:11435 HTTP API, sidecar watch.
Rust host (gateway)crates/cinderpaw-cli/Rust, no UIThe same cinderpaw-core headless. Exposes the cinderpaw subcommands and the HTTP API for terminal and automation.
SidecarCinderpawAgent/Bun + TypeScript, one compiled binaryThe helper loop, BRSI engine, recall, tools, safe answering router.
TUItui/Go + Bubble TeaTerminal chat, onboarding, connectors wizard. API client only.

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

NameBetweenHow they talkChecked by
Tauri IPCUI ↔ hostinvoke() / listen('cinderpaw://…')Command registry in src-tauri/src/commands/
JSON-lines on stdouthost ↔ sidecar{type:"…", …} one per lineCinderpawAgent/src/transports/tauri.ts + types.ts
OpenAI/Ollama-compat HTTPany client ↔ host loopbackJSON over HTTPcrates/cinderpaw-core/src/api.rs, per-launch bearer token

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.

LayerJob and rulesWhere in the code
L0SubstrateGit-backed journal, the bounded-ratchet boundary, integrity.rsi/infra/journal.ts · rsi/infra/hash-chain.ts · cinderpaw-core/src/rsi/repo.rs
L1Config evolutionMutates the 7-field GenomeConfig, bounded by schema. May not touch code or weights.rsi/l1-config/
L2Personal adaptationLoRA over your own signal. May not mutate base weights.rsi/l2-adapt/
L3Code RSIUnified diffs over CinderpawAgent source, applied through a worktree. May not skip the worktree or touch the host.rsi/l3-code/
L4Architecture evolutionSubsystem hot-plug behind two v1 seams: retrieval_strategy and planner. May not write into CinderpawAgent/src/.rsi/l4-modules/
L5Governance evolutionTunes parameters inside SandboxBounds. Reversible. May not bypass tier-0.rsi/l5-gov/ · cinderpaw-core/src/rsi/sandbox_bounds.rs
L6Meta evolutionTunes the algorithm that produces those parameters. Never skips the human gate.rsi/l6-meta/meta-evolution.ts
infraCross-layerBus events, envelopes, budget, paths, the contract FSM, confidence gate.rsi/infra/

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.

A new answering provider

Four places, in this order: cinderpaw-core/src/byok.rs provider_catalog() is the canonical list; CinderpawAgent/src/egress/inference-providers.ts only if you need a new protocol family; check the auto-seeded vector in brain/capability-registry.ts; the Cloud Keys UI wires itself through useCatalog().

A new built-in tool

One file: CinderpawAgent/src/tools/builtin/<name>.ts. Declare the manifest (permissions, parameters) in the same file and boot.ts picks it up. Add a smoke test under CinderpawAgent/tests/.

A new chat connector

Catalog entry in cinderpaw-core/src/connectors.rs, desktop IPC in src-tauri/src/connectors.rs, connection owner in CinderpawAgent/src/egress/mcp-manager.ts. Persistence flows through cinderpaw-core so desktop and gateway agree.

A new L4 seam module

modules/<id>/manifest.json + module.ts. The registry at modules/registry.json is the runtime source of truth. Never edit CinderpawAgent/src/ for a module - that's the L3 trust boundary.

A new memory strategy

Pick the layer first. Same engine, different scoring goes in rsi/l1-config/fitness.ts. A new retriever joins the GenomeConfig.retrievalStrategy pool. A new storage layout belongs in CinderpawAgent/src/memory/fractal/.

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

Every message goes to the Bun and TypeScript sidecar. It recalls good recall. It sends words live. It loops tool calls till it has an answer. A safety stop ends it at 500 loops. By default a turn starts no new loops after 20 minutes. Change that with CINDERPAW_TURN_BUDGET_MS.

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.

RecallKept inWhat it keeps
WorkingRAMThe live conversation transcript. Auto-compresses older turns when it runs over the token budget.
EpisodicSQLite + FTS5Every message, tool result and typed observation, keyword-searchable full-text.
SemanticSQLiteDurable facts pulled from each turn: your name, role, language, preferences, constraints.
Fractal MemoryRAPTOR treeThe semantic layer. Events are embedded, k-means-clustered, and each cluster is summarized into a tree; recall embeds your query and walks the tree for related memories across every session. Built offline, and it augments FTS5 instead of replacing it.
Recall Engine-Joins all of the above. Adds the best hits first. Before each answering call.

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.

StepWhat it changesPromotion constraints
L1Config EvolutionIts own settings - sampling, memory, retrieval and tool parameters. Runs “dream cycles” while you're away.A population competes on a fitness score; the champion is only replaced on a measured win.
L2Personal AdaptationA private LoRA adapter trained on how you actually work, on your own GPU.Gated by an A/B evaluation before promotion; passing an evaluation does not guarantee improvement on every task.
L3Self-Code ModificationIts own source code. Cinderpaw proposes patches, tests them, and keeps only what passes.Bounded diff size, an immutable core it can't touch, sandboxed, auto-rollback on regression.
L4Tool / Module EvolutionIts own tools. It builds new ones autonomously, improves them over time, and retires the ones that stop earning their keep.Every module is eval-scored and lifecycle-managed behind a module wall.
L5Governance EvolutionThe knobs of the improvement policy itself - confidence thresholds, fitness weights, mutation rates, budgets.Only moves within agent-immutable bounds it cannot widen; every change is reversible.
L6Meta EvolutionThe algorithm that produces those knobs - how it decides what to try and how it learns. Genuine recursive self-improvement.Always human-gated. Research preview, behind the strictest promotion gate.

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.

ToolNeedsWhat it does
tool_forgeprocessCreate, update or delete its OWN tools. New tools transpile-check, hot-register instantly, persist in ~/.cinderpaw/tools and run sandboxed - the agent extends its own tool surface at runtime.
list_tools-Discover and enable optional tools on demand, keeping the base set lean (the tool drawer).
tool_health-Per-tool success rate and latency report; the agent diagnoses its own failing tools.
web_searchnetworkRanked web results from DuckDuckGo, no key needed. Set CINDERPAW_SEARXNG_URL to use your own SearXNG instead.
read_webpagenetworkClean Markdown from any URL via Jina Reader.
deep_researchnetworkIterative plan → search → read → extract → synthesize; returns a cited report.
fetch_urlnetworkFetch any public HTTPS URL (SSRF-guarded, rate-limited, audited).
http_requestnetworkFull HTTP client for APIs: GET/POST/PUT/PATCH/DELETE with headers and JSON.
read_filefs:readRead a file from the workspace.
write_filefs:writeWrite a file; creates intermediate directories.
edit_filefs:writePrecise find-and-replace edits in place, not just whole-file writes.
list_directoryfs:readList directory contents.
file_searchfs:readFind files by name or glob under an allowed root.
grepfs:readRegex search across files, ripgrep-style.
git_statusprocessRun git (status, diff, log) in the workspace.
shell_execprocessRun shell commands. Gated by CINDERPAW_ENABLE_SHELL_EXEC.
scan_workspacefs:readDetect hardcoded secrets and code anti-patterns. Never exposes secret values.
recall-Search past conversations (episodic + Fractal Memory) for relevant context.
remember-Write a durable fact into semantic memory on demand.
self_describe-Introspect its own recent activity, tools and state.
delegate_task-Hand a self-contained sub-task to a fresh sub-agent (optionally in parallel), depth-guarded.
ask_user-Pause and ask you when the task genuinely forks - routed to wherever you are.
escalate_to_human-Hand off to the human owner when it shouldn't act alone.
connectors_manage-List and configure its own chat connectors, all 21 of them: Discord, Slack, WhatsApp, Telegram and more (tokens write-only).
computer_useprocessDrive desktop apps through the OS accessibility tree: read the UI, find elements, click and type.
list_skills / read_skillfs:readDiscover and read installed SkillHub skills.
calculator · time_date · todo_write-Everyday helpers: exact math, dates and times, and a working to-do list across a task.

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, plus where you heard about Cinderpaw if you press one of the buttons for it.
  • This website. It counts visits and Download presses per channel: one word, like reddit, youtube or direct, taken from the link you followed or the site you came from. No cookie, no page, nothing about you. Your address is used for up to an hour to stop abuse, and never stored.
  • 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.
  • Daily usage summary. Off unless you say yes: a box on the last setup screen, a one-time question on the home screen, or Settings then Privacy. If you say yes, once a day it sends its version, your OS and, for each model, things like which service ran it, how many tasks it did and how they ended, time ranges, tokens, cost, tool calls and your thumbs up and down counts. Never your messages, file names, links, keys or exact times. A random code that changes every month lets us count installs without following anyone. Each summary is saved to ~/.cinderpaw/telemetry-sent.jsonl before it leaves, and Settings then Privacy shows that file. Turn it off and sending stops at once.
  • Leaderboard. The totals from those summaries, added up across everyone who said yes, are public on the Leaderboard tab in Models.

The full list, in plain words, is in PROMISES.md.

Environment variables

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

SettingIf you do nothingWhat it does
CINDERPAW_WORKSPACEcwd + homeFilesystem roots file tools may touch. Set it to RESTRICT.
CINDERPAW_FS_DENY-Extra paths file tools may never touch (on top of ~/.cinderpaw + ~/.ssh).
CINDERPAW_BASE_URL127.0.0.1:11435Answering spot. Cinderpaw's own llama.cpp engine.
CINDERPAW_API_KEY-Bearer token for the answering spot (BYOK / local token).
CINDERPAW_MODELqwen2.5:7bModel name (overridden to cinderpaw-local by the desktop app).
CINDERPAW_ENABLE_SHELL_EXECtrueRegister the shell_exec tool. Set false to disable shell access.
CINDERPAW_SEARXNG_URL-Origin of a SearXNG instance for web_search.
CINDERPAW_FETCH_DOMAINS-Domain allowlist for fetch_url. Unset = all public hosts (SSRF guard still applies).

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.

Ready to try it?

Get it in one command. Or take the installer for your OS from GitHub.