ExcaVelo

한국어 README: README.ko.md

Transform raw memos into structured notes using Claude. Works with your existing Claude Code login (Pro/Max) or with an Anthropic API key.

Why

You scribble fragmented notes during a meeting or a quick thought. You want them turned into proper meeting minutes, a 1:1 summary, a decision record, or your own template — without leaving Obsidian and without copy-pasting into a chat.

ExcaVelo takes:

• your pre-set context (who you are, what team, what project),
• any per-note context you added,
• the memo body — the part of the note ExcaVelo will rewrite,
• a template you choose,

and produces a clean, structured note via Claude. The memo body is preserved by default.

Quick start

1. Install ExcaVelo from Obsidian Community Plugins (or load it as an unpacked plugin during development).
2. Choose one of:
   • Claude Code CLI (recommended) — if you already use Claude Code on the desktop with a Pro/Max subscription, the plugin auto-detects and uses it. No API key needed.
   • Anthropic API key — paste a key from console.anthropic.com. Pay-per-token. Works on mobile.
   • OpenAI-compatible endpoint — point at OpenAI, Ollama, LM Studio, Groq, Together, OpenRouter, etc.
3. Fill in Default context in settings — one paragraph about who you are and what you work on.
4. Either open any note and type / paste your memo content, or run ExcaVelo: New note from template to create a fresh note with a pre-filled [!context] callout scaffold.
5. Run ExcaVelo: Transform note... from the command palette (or click the wand icon in the ribbon).
6. Pick a template. Review the preview. Save as new file, append below, or copy.

How the plugin reads your note

ExcaVelo splits the prompt into three parts:

Only the memo body is rewritten. Anything inside [!context] is background — the LLM reads it but does not transform it.

Example:

> [!context]
> Today is a 1:1 with Park, infra team senior.
> Topic: migration risk assessment.

- migration phases — risk
- A: blue-green, B: incremental
- Park prefers B (simpler rollback)
- need a decision by Tuesday

The two lines inside the callout become the note-specific context. The four bullets below become the memo body. The "Default context" you set in Settings is always prepended on top of both.

If a note has no [!context] callout, the entire note becomes the memo body. The Default context from Settings still applies.

Tip: if you only want to transform part of a long note, select that region in the editor before running Transform — selection wins over the full note body.

If writing the [!context] callout by hand each time is tedious, use ExcaVelo: New note from template (command palette). It creates a fresh note with the callout scaffold and a placeholder body, so you only fill in the blanks and start writing.

Templates

Templates are plain markdown files under excaVelo/templates/ in your vault. Edit them, add new ones, share them. The format is documented in docs/templates-format.md. Five starter templates are copied in on first run:

• meeting-minutes — participants, discussion, decisions, action items
• 1on1 — themes, decisions, watch items, tone signal
• daily-memo — highlights, grouped notes, actions, open questions
• decision-record — ADR-style record
• brainstorm — clustered themes, strong candidates, next steps

Authentication paths

Claude Code CLI (recommended for Claude Pro/Max users)

The plugin spawns your installed claude CLI as a subprocess. Auth lives in Claude Code (claude login), so the plugin never sees a key. Works with personal Claude Pro accounts and with team-shared Claude Max accounts.

Requires: Claude Code installed and logged in. Desktop only — on mobile, ExcaVelo transparently falls back to the Anthropic API key path (a one-time notice tells you).

A note on Anthropic terms: spawning your own logged-in claude CLI is mechanically the same as running it yourself in a terminal. ExcaVelo does not redistribute any Anthropic licence and stores no Anthropic credentials. Using Claude Code as a backend for another tool is not a documented use case in Anthropic's product docs — use the CLI path knowing that, or pick the API key path instead.

Anthropic API key

Standard pattern. Get a key at console.anthropic.com, paste into settings. Pay-per-token billing — separate from any Claude.ai subscription. Works on mobile and desktop.

OpenAI-compatible endpoint

For OpenAI itself, or any local / hosted server that speaks the OpenAI Chat Completions shape (Ollama, LM Studio, Groq, Together, OpenRouter, vLLM, Fireworks, Mistral, ...).

Privacy

• Your API key (when used) is stored locally in data.json inside your Obsidian plugin folder. It is never sent anywhere except to the provider you configured.
• When using Claude Code CLI, the plugin only spawns a local subprocess. No keys or tokens are stored by the plugin.
• No telemetry, no analytics, no remote logging.
• Network requests are made only when you trigger a transform — never on install, settings open, or vault scan.

Wiki integration

If your vault includes an excavelo.json at root, the plugin enables smart defaults — output paths and frontmatter that match the structure of Karpathy-style LLM Wiki vaults (raw/, wiki/sources/). See docs/architecture.md for the config schema.

Development

pnpm install
pnpm dev     # esbuild watch
pnpm build   # production build

Uses pnpm (declared in packageManager). If you don't have it: npm i -g pnpm or corepack enable.

Symlink (or copy) the build output (main.js, manifest.json, styles.css) into a test vault's .obsidian/plugins/excavelo/ to try it.

Architecture overview: docs/architecture.md. Provider implementation notes: docs/adapters.md. Template format: docs/templates-format.md. Developer spec: CLAUDE.md.

License

MIT. See LICENSE.