AI remembers. Rill thinks.
Website · Download · Spec · Architecture
Rill is a personal knowledge management system powered by Claude Code. It turns fragments of thought — spoken, typed, clipped, forwarded — into structured, searchable knowledge you own.
Everything Rill produces is plain Markdown. Git is the single source of truth. Claude Code is the processor. You keep all of it on your own machine.
Status: v0.1 public preview. Expect rough edges, sharp changes, and short iteration cycles. Report issues.
Rill makes the most sense if:
- You already use Claude Code daily and have a Max Plan subscription (~$20/month)
- You take notes regularly (journals, meetings, idea fragments) and want them distilled rather than just stored
- You prefer local-first, file-based tools where Git is the system of record
- You are comfortable with a CLI workflow alongside a desktop GUI
Rill is probably not for you if:
- You want cloud sync, a web-only UI, or multi-user collaboration
- You want a polished consumer product, not a v0.1 system you can hack on
- You do not want to add Anthropic to your AI vendor list
Most PKM tools are filing cabinets: they store what you put in, exactly how you put it in. Rill is a thinking layer on top of one: you drop in raw input (a voice memo, a meeting transcript, a clipped tweet), and Claude Code distills it into atomic notes, tasks, and entity records. The originals stay immutable; the distilled layer is evergreen.
You interact with it through natural language in Claude Code — no custom UI to learn. The files are Markdown, so every tool you already use (Obsidian, VS Code, grep) keeps working.
The Rill desktop app. Timeline of journal entries, meetings, and generated daily notes, with the current entry rendered on the right.
flowchart LR
V["🎙 Voice / Text"] --> J["inbox/journal"]
P["🔌 Plugins<br/>(Gmail, Meet, Twitter…)"] --> IB["inbox/*"]
J --> Distill["/distill"]
IB --> Distill
Distill --> K["📚 knowledge/"]
Distill --> T["✓ tasks/"]
WS["🧠 workspace/<br/>(deep thinking)"] -->|"/close"| K
K -.query.-> WS
K --> Out["📰 reports/<br/>📄 pages/"]
T --> Out
Rill organizes data into layers: input (immutable, what you captured), thinking (workspaces for deep work), knowledge (evergreen distilled notes + entities), action (tasks), and output (daily briefings, newsletters, aggregated pages). Skills like /distill, /focus, and /briefing move data across the layers. See docs/architecture.md for the full flow.
A native macOS app ships alongside the CLI. Use the app for reading and navigation; use Claude Code in the terminal for creation and thinking.
- Download: latest DMG at github.com/rillmd/rill/releases (arm64 + x64, signed & notarized)
- Or install via LP: rill.md
The app and CLI read the same vault. Start with either; they stay in sync through the filesystem.
| Skill | What it does |
|---|---|
/onboarding |
First-time setup and tutorial |
/morning |
Daily reports: /briefing + /newsletter in parallel |
/distill |
Extract knowledge, tasks, and entities from inbox entries |
/briefing |
Generate today's daily note from recent activity |
/newsletter |
Generate a research report based on your interests |
/focus |
Start or resume a deep thinking workspace |
/close |
Complete a workspace and distill insights to knowledge |
/page |
Create and update human-facing aggregated views |
/sync |
Run plugin adapters to pull external sources |
/solve |
AI-assisted execution of a task ticket |
/inspect |
Audit knowledge note metadata quality |
/repair |
Fix metadata issues detected by /inspect |
/maintain |
Run scheduled maintenance passes |
/eval |
Benchmark skill performance |
/clip-tweet |
Ingest a tweet URL into the web-clips layer |
/plugin |
Interactive plugin management |
Every skill is a single Markdown file in .claude/commands/. Read the file to see exactly what it does — there is no hidden logic.
- macOS 12+ (for the desktop app), or any OS with a terminal (for CLI only)
- Claude Code with a Max Plan subscription (~$20/month, separate from Rill)
- Git,
jq
curl -fsSL https://raw.githubusercontent.com/rillmd/rill/main/install.sh | bashInspect the script first: install.sh on GitHub.
The installer clones Rill, creates a vault at ~/Documents/my-rill, and symlinks the rill CLI. It does not modify your shell profile; it prints the PATH line for you to add.
cd ~/Documents/my-rill
claudeThen type /onboarding. This walks you through a first journal entry, your first /focus + /distill cycle, and the "ask Claude anything" muscle that you'll use daily.
Rill runs inside Claude Code. Once you're in your vault with claude started, just talk to it in natural language:
"capture this thought: ideas about project architecture"
"clip https://example.com/interesting-article"
"give me today's briefing" / "what's worth reading today based on my interests?"
"help me think through the API redesign"
"pull in any new entries from my plugins and extract what's useful"
Claude routes each of these to the right skill internally — /focus, /distill, /briefing, /newsletter, /sync — so you don't need to remember command names. You can also just ask questions: "what did I decide about X last week?" / "summarize my meetings with the finance team." Claude reads the relevant files directly.
For quick capture from outside Claude Code, a few shell commands are available:
rill log "Notes from today's meeting" # quick journal entry from anywhere
rill clip https://example.com/article # clip a URL
rill push # git add + commit + pushRun rill help to see the full CLI surface. Anything beyond quick capture is best handled by asking Claude inside your vault.
my-rill/
├── inbox/
│ ├── journal/ # Your thoughts (rill log)
│ ├── meetings/ # Meeting notes
│ ├── tweets/ # Saved tweets
│ ├── web-clips/ # Web articles
│ └── sources/ # Other external input
├── knowledge/
│ ├── me.md # Your interest profile
│ ├── notes/ # Atomic knowledge (distilled)
│ ├── people/ # Person entities
│ ├── orgs/ # Organization entities
│ └── projects/ # Project profiles
├── workspace/ # Deep thinking sessions
├── tasks/ # Task tickets
├── reports/
│ ├── daily/ # Daily notes (/briefing)
│ └── newsletter/ # Research reports (/newsletter)
├── pages/ # Aggregated views
├── taxonomy.md # Tag vocabulary
└── CLAUDE.md # Claude Code instructions
Not sure which inbox subdirectory a file belongs in? Drop it into inbox/sources/ — or directly into inbox/:
cp ~/Downloads/random-notes.md ~/Documents/my-rill/inbox/sources/
# or simply
cp ~/Downloads/random-notes.md ~/Documents/my-rill/inbox//distill processes both locations. It organizes the file, extracts tasks, and creates knowledge entries through a generic pipeline — the same one that runs on meetings or clipped articles. If /distill recognizes the content as a more specific type (a meeting, a tweet), it may reclassify.
- Any Markdown file in
inbox/sources/or directly underinbox/ - Frontmatter is optional; if missing, Rill infers
createdandsource-typeautomatically
- Non-Markdown files (PDFs, images, raw audio). Transcribe or summarize them in a Markdown file first
- Binary files containing personal information — these should stay out of Git; commit only the Markdown transcript
For recurring external sources (Gmail, Google Meet, Twitter), use a plugin instead — plugins have type-specific distillation that extracts richer structure from known formats.
Rill is local-first:
- Your data lives as plain Markdown on your disk. Nothing is synced to a Rill-operated server. There is no Rill server.
- Your vault is a Git repository. Keep it local, push it to a private GitHub repo, self-host it — whatever fits your trust model.
- AI processing happens through Claude Code. When you invoke a skill or ask a question, Claude Code sends the relevant file contents to Anthropic's API under your Max Plan subscription. Rill itself holds no API keys and makes no network calls.
- No telemetry. The
rillCLI is a bash script. It does not phone home. Search the code: bin/rill.
You can audit everything Rill does by reading the bash script and the skill files. Nothing runs except what you invoke.
Rill is not a note-taking app — it's a distillation layer. If you want a beautiful editor, use Obsidian. If you want cloud-hosted AI retrieval, use mem.ai. If you want an MCP-based knowledge graph, use Basic Memory.
Rill's value is: you keep the files locally, and Claude Code distills them in place. The thinking happens in Claude Code, not in a separate app you have to learn.
- Bugs & features: GitHub Issues
- Discussions: GitHub Discussions
- Updates: @rill_app on X/Twitter
Discord is not offered at this stage — GitHub is the single channel.
Rill's behavior lives in its source files. When you run claude inside a Rill vault, Claude Code reads these to answer your questions — but you can read them directly too:
| Area | File(s) |
|---|---|
| Information architecture | docs/architecture.md |
| Skill behavior | .claude/commands/*.md |
| Directory conventions | .claude/rules/rill-*.md |
| File placement rules | inbox/<type>/CLAUDE.md |
| Plugin authoring | plugins/README.md |
| Skill spec examples | docs/skill-specs/ |
| Full specification | SPEC.md |
You rarely need to read any of these directly — just ask Claude. They exist for transparency and audit.
cd ~/src/rillmd/rill && git pull
rill updaterill update syncs the latest skills and rules to your vault. Your personal data and custom skills are never touched. Your vault's own git history stays intact.
Rill supports plugins for ingesting data from external services. The plugins/ directory lists what ships by default; see plugins/README.md for how the plugin system works and how to author your own.
You can install a plugin by asking Claude inside your vault — "install the google-meet plugin" — or by running rill plugin install <name> and rill plugin enable <name> from the shell.
- docs/architecture.md — Information architecture overview
- SPEC.md — Full system specification
- docs/creating-skills.md — Authoring your own skill
- plugins/README.md — Plugin system and authoring
Rill is inspired by years of using Obsidian and watching the Claude Code ecosystem mature. The distillation pipeline owes a debt to Andy Matuschak's evergreen notes, Andrej Karpathy's LLM Wiki pattern, and Basic Memory's MCP-first approach.