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.
Is This for Me
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
Why Rill
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.
Screenshots
How It Works
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.
Desktop App
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.
The app and CLI read the same vault. Start with either; they stay in sync through the filesystem.
Core Skills
| Skill | What it does |
|---|
/onboarding | First-time setup and tutorial |
/morning | Daily reports: /briefing + /newsletter, run sequentially inline |
/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 |
/pulse | Refresh your current-state snapshot (direction, open work, recent decisions) |
/retrospective | Generate a weekly retrospective across workspaces and decisions |
/focus | Start or resume a deep thinking workspace |
/close | Complete a workspace and distill insights to knowledge |
/project | Manage a project execution hub — status, next task, or an autonomous run |
/refresh-project | Recompute a project's active tasks and related workspaces |
/refresh-decisions | Recompute a project's pending human-decision digest |
/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 — canonically skills/{name}/SKILL.md (deployed to your vault as .claude/skills/{name}/SKILL.md). Read the file to see exactly what it does — there is no hidden logic.
Quick Start
Requirements
- 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
Install
curl -fsSL https://raw.githubusercontent.com/rillmd/rill/main/install.sh | bash
Inspect 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.
First run
cd ~/Documents/my-rill
claude
Then 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.
Daily Usage
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.
Power-user shortcuts
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 + push
Run rill help to see the full CLI surface. Anything beyond quick capture is best handled by asking Claude inside your vault.
Vault Structure
my-rill/
├── inbox/
│ ├── journal/ # Your thoughts (rill log)
│ ├── meetings/ # Meeting notes
│ ├── tweets/ # Saved tweets
│ ├── web-clips/ # Web articles
│ └── sources/ # Other external input
├── knowledge/
│ ├── self/ # Your self entity (profile, interests, direction, ...)
│ ├── notes/ # Atomic knowledge (distilled)
│ ├── people/ # Person entities
│ └── orgs/ # Organization entities
├── projects/ # Execution hubs bundling related tasks
├── 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
The inbox/ Drop Zone
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.
What works
- Any Markdown file in
inbox/sources/ or directly under inbox/
- Frontmatter is optional; if missing, Rill infers
created and source-type automatically
What doesn't
- 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.
Privacy & Data Flow
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
rill CLI 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.
How It Compares
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.
Community & Support
Discord is not offered at this stage — GitHub is the single channel.
Deep Dive
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:
You rarely need to read any of these directly — just ask Claude. They exist for transparency and audit.
Updating
rill update
rill update pulls the latest source itself, then 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.
Plugins
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.
Documentation
Acknowledgments
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.
License
MIT
