rikkahub-agent-pure

RikkaHub Agent · Pure is an independent, hardened continuation of the on-device Android agent from ExTV/rikkahub-agent (itself built on RikkaHub). It keeps the entire upstream surface and adds one layer that answers a single question:

Can this run for hours without blowing up the context — or the bill?

Why this project · What's added · What it can do · Screens · Get started · Docs · 简体中文

Why this project

rikkahub/rikkahub                     the original native Android LLM chat client
   └─ ExTV/rikkahub-agent             adds the agent layer: device tools, workflows,
        │                             shells (Shizuku/Termux), sub-agents, Telegram bot…
        └─ wuyhong715/rikkahub-agent-pure    ★ this repo — the "Pure" hardening pass

Upstream's agent layer was built feature-first: the goal was to add capabilities, not to make a long unattended run survive its own output. Six things got in the way — every tool schema injected every turn; compaction that only fires on a token threshold; one logcat dump able to flood the context; sub-agents receiving only a bare task string; tokens counted but never attributed; and headless paths (cron, workflows) that auto-approved everything.

Pure removes nothing. It keeps the whole upstream surface and makes a long run survivable, observable and capped.

Note — since 2026-10-07 this repository is standalone: it is no longer a GitHub fork and no longer auto-syncs from upstream.

The seven additions

Every one of these is off by default — with the switch off, the default path is unchanged (several are byte-for-byte identical to upstream).

Full detail — what each one does, the exact tool names, and where every switch lives — is in docs/PURE-FEATURES.md.

What you can do with it

See where the money goes. "How much did sub-agents cost me this week?" — the Statistics page groups the ledger by day / purpose / model / assistant and shows tok/s, and the orchestration tree lays out every parent → child dispatch. Cost is frozen at write time, so history doesn't shift when a provider changes its rates.

Cap a run. Set an orchestration token budget on an assistant — it covers the parent turn and everything it fans out. A dispatch that would exceed it is refused before it starts, with a readable reason the model can act on. Each expert can carry its own ceiling.

Run a long job unattended. "Refactor this module, run the tests, and keep going until they pass." A tool result that would flood the context is capped and spilled to disk with head + tail kept; the model can compress the conversation on its own; and the run holds a foreground service so switching apps doesn't kill it.

Build a team. "Create an expert called researcher that only uses web tools on the cheap model, and a coder that can edit files." Then: "dispatch the researcher to find X and the coder to implement Y, in parallel." Experts persist with their own namespace and memory, so you name them instead of re-describing them each time.

Keep a library. Point cold memory at a folder of Markdown; the agent indexes it and reads only what it needs. A large knowledge base costs nothing until it's actually read.

Wire up the boring stuff. "When I connect to the office WiFi, POST my status to this API." Workflow actions can pass data to each other and pull credentials from an encrypted store, so tokens never sit in the workflow definition.

Travel light. Turn on the tool palette and the agent searches for the tool it needs, instead of carrying every schema on every turn.

Screens

Getting started

0 · Install

Download the latest APK from Releases — or build from source (below).

It is a signed, R8-optimized build (excp.rikkahub.debug): it installs side by side with a release build of the upstream app.

1 · Add a model provider

Settings → Providers → pick one → paste your API key.

• OpenRouter — first-class support (auto-detected capabilities, pricing, routing, fallback models)
• Codex / Grok — sign in with your OpenAI / xAI account (OAuth, no key)
• Local · LiteRT — download a model (Gemma, Qwen) and run it on-device, no network
• AICore — Gemini Nano on Pixel 8/9/10 (AICore Beta)
• …or any OpenAI-compatible endpoint

2 · Turn on the tools you want

Settings → Assistant → tap your assistant → Local Tools — flip the groups you want. If you turn nothing on, the app behaves exactly like vanilla RikkaHub.

Inside an enabled group you can now switch individual tools off, not just the whole group. And Settings → Sub-agent profiles → Tool palette lets you search the whole tool directory (57 groups, ~180 tools) to find where a tool lives before enabling it.

3 · Your first conversation

1. Leave Settings and open a new chat.
2. Ask something that uses a tool: "What's my battery level?" — approve the tool call when it asks.
3. Tap the tool call in the reply to inspect the result and re-run it with the same arguments, without spending a new turn.
4. Try a multi-step one: "Find the PDFs on my phone and summarise the one about invoices."
5. Open the chat drawer → Statistics to watch the tokens land in the ledger.

That's the upstream experience. Everything below is the Pure layer — all optional.

4 · Turn on the Pure features

A. Budgets and the ledger — Assistant → Basic Settings: Tool result budget, Orchestration token budget, Concurrent sub-agents. Then: chat drawer → Statistics for the ledger and orchestration tree. Price table: Settings → Providers → model → Price tab.

B. The advanced switches — Assistant → Basic Settings → Advanced / experimental card (off by default, read the risk note):

• Model-initiated context compaction (compact_context)
• Tool surface mode (tool_search / tool_open)
• Sub-agent context references
• Freeze sub-agent tool surface

C. Experts — Settings → Sub-agent profiles: create an expert with its own prompt, model, tool surface, MCP servers, skills and namespace. Then just dispatch to it by name.

D. Cold memory — bind a workspace (Assistant → Basic Settings), then Assistant → Memory → Cold memory (Markdown) and pick a folder.

E. Workflow secrets — Settings → Workflows → open one → API secrets; reference them from a web_fetch header as {{secret:NAME}}.

Cheat sheet · where things live

Requirements

Build from source

Requires JDK 17, the Android SDK (platform-tools), and bun + pnpm on your PATH (bun installs the web-ui dependencies, pnpm builds