Writers Alembic

Alembic

AI writing workflows for Obsidian, with prompts you can create and share. Workflows live in your vault as Markdown files: edit them, share them, run them on any note.

---

Quick start

1. Install the plugin (see [[#Installation]])
2. Open Settings → Writers Alembic → Providers and configure at least one AI backend
3. Open any note, optionally select some text, and run Writers Alembic: Run workflow from the command palette
4. Pick a workflow and see the result in your note

---

Installation

Alembic is a desktop-only plugin (it shells out to CLI tools and makes direct HTTP calls to local AI servers). No API keys needed for things like Claude, Gemini, etc. if you have the CLI tools installed (e.g. Claude Code).

Manual install:

1. Download main.js, styles.css, and manifest.json from the latest release
2. Copy them into .obsidian/plugins/writers-alembic/ inside your vault
3. Enable the plugin in Settings → Community plugins

Via BRAT:

1. Install BRAT
2. Add the Alembic repository URL
3. Enable the plugin
4. On macOS, Obsidian's PATH does not include Homebrew by default. The plugin handles this automatically — no manual PATH configuration needed.

---

Providers

Go to Settings → Writers Alembic → Providers to add and configure backends. You can have as many as you like; each workflow can target a different one.

Claude CLI (default, no API key needed)

Requires the Claude CLI to be installed and authenticated. Runs claude --print under the hood. No API key required in the plugin; authentication is handled by the CLI itself.

npm install -g @anthropic-ai/claude-code
claude   # follow the login prompts

Anthropic API

Enter your API key from console.anthropic.com. Hit Test connection to fetch the live model list and pick one.

Gemini API

Enter your API key from aistudio.google.com. Hit Test connection to see available models.

Gemini CLI

Requires the Gemini CLI to be installed and authenticated.

Ollama

Point the Base URL at your Ollama instance (default: http://localhost:11434). Hit Test connection and your installed models will appear as chips below the model field. Click one to select it.

OpenAI

Enter your API key from platform.openai.com. The base URL defaults to https://api.openai.com/v1 but can be changed for compatible local servers.

OpenRouter

Enter your API key from openrouter.ai. One key covers dozens of models from Anthropic, Google, Meta, Mistral, and others.

---

Running workflows

Command palette

Run Writers Alembic: Run workflow to open the picker. The freeform entry is always pinned at the top; your saved workflows follow. Fuzzy search works across all names.

Direct commands

Every workflow is also registered as its own command: Writers Alembic: [Workflow Name]. Assign a hotkey to any workflow in Settings → Hotkeys for one-keystroke access.

Selection required

Workflows whose prompt uses {=SELECTION=} require you to select text before running them. If nothing is selected, a flash message reminds you instead of running with empty input.

Where the output goes

What happens with the AI's response depends on replaceSelection and whether you ran the workflow with text selected:

• Selection + replaceSelection: true — the selected text is replaced with the output.
• No selection + replaceSelection: true + a prompt using {=CONTEXT=} (not {=SELECTION=}) — Alembic treats this as a full-note workflow (like Lint or Add Structure) and replaces the entire document.
• No selection + replaceSelection: false — the output is inserted at the cursor.

Canceling a run

While a workflow is running, the notice in the corner has a Cancel button. Clicking it stops the in-flight request immediately.

Freeform (Ask Claude)

Selecting Ask Claude from the picker opens a text box where you type a one-off instruction. The current note is always included as context. Use the Humanize output toggle to run the result through the Humanize workflow automatically.

---

Built-in workflows

---

Workflow files

Every workflow is stored as a plain Markdown file inside your workflows folder (default: _alembic). You can see and change the folder path at the top of the Workflows settings tab.

The built-in workflows (the ones Alembic installs on first run) come from a workflows/ folder in the plugin repo. They are bundled into the plugin at build time and written to your vault verbatim. You can read them, copy them, and edit them just like any other workflow file.

A workflow file looks like this:

---
name: "✂️ Tighten This Up"
id: "default-tighten"
prompt: "{=SELECTION=}"
replaceSelection: true
humanize: true
linkDepth: 1
providerId: "default-claude-cli"
---

You are a ruthless copy editor. Your goal is maximum signal per word...

Frontmatter fields:

The file body is the system prompt. Leave it blank for a basic assistant with no special instructions.

---

Token placeholders

Use these placeholders to inject live note content at run time. They substitute in both the prompt field and the file body (system prompt), so the system prompt can reference the same content the AI is about to see.

If you leave prompt blank, Alembic sends whatever is available: selected text first, then the full note.

---

Link expansion (linkDepth)

When linkDepth is set to 1 or higher, Alembic follows [[wikilinks]] in your note and includes the content of the linked notes as additional context sent to the AI. This gives the model a richer picture of related material without you having to copy-paste.

Set it per workflow in Settings → Writers Alembic → Workflows: pick a workflow and use the Link depth dropdown in the detail panel. You can also set linkDepth: 0–3 directly in the workflow file's frontmatter.

• 0 — No expansion. Only the current note is sent.
• 1 (default) — Includes notes linked directly from the current note.
• 2–3 — Follows links recursively (links in linked notes, etc.). Useful for deeply interlinked knowledge bases but can produce large payloads.

How linked content gets injected: each linked note is appended after the current note's content, separated by --- and a **Linked note: <basename>** header. A note reachable via multiple paths is included only once per run, so cycles are safe.

Link expansion reads files directly from your vault — no network calls, works offline. If the combined context exceeds ~100 KB, Alembic will show a confirmation prompt before sending.

---

Creating a workflow

From settings: click + in the Workflows sidebar. A new file called New Workflow.md is created in your workflows folder. Edit the frontmatter and body, hit Save, and the workflow is immediately available.

Directly in the vault: create any .md file in your workflows folder with valid frontmatter (the id field is required and must be unique). Alembic picks it up automatically, no restart needed.

---

Updating workflows

Two buttons in Settings → Writers Alembic → Workflows help you stay current.

Reset to default appears at the bottom of the detail panel for any built-in workflow. It overwrites that file with the prompt bundled in your installed version. Use it to undo edits you don't want to keep, or to pick up prompt improvements that shipped with a plugin update. Works offline.

↓ pull new workflows sits at the bottom of the workflow list. It checks the plugin's GitHub repo and adds any workflows that don't already exist in your vault. It never touches files you already have, including ones you've edited. Requires an internet connection.

Neither button affects workflows you've created yourself.

---

Sharing workflows

Because workflows are just Markdown files, sharing is the same as sharing any note:

• Drop a .md file into someone else's _alembic folder and it shows up immediately
• Share them as Obsidian attachments, GitHub Gists, or Discord pastes
• Version-control your whole _alembic folder in git
• Submit a pull request to add it to the plugin defaults (see [[#Contributing workflows]])

The only thing that won't transfer is the providerId. The recipient will need to update that field to match one of their own provider profiles, or it falls back to the first available provider automatically.

---

Contributing workflows

The built-in workflows ship from a workflows/ folder at the root of the plugin repo. Each file is plain Markdown with YAML frontmatter. The build step reads them and bundles the content into the plugin.

To add a new workflow to the defaults:

1. Fork the repository
2. Create a file in workflows/ named after the workflow, e.g. My Workflow.md
3. Add the frontmatter and write your system prompt as the file body
4. Open a pull request

The PR diff shows the prompt text directly. Reviewers can read it, suggest edits, and approve it the same way they would any other change. No compiled output to audit.

What makes a PR worth merging:

• One job. The best workflows have a clear input, a clear output, and no ambiguity about when to run them. If you can't describe it in one sentence, split it.
• A stable id. Use something specific like contrib-workflow-name. The id must not change after a workflow ships, so get it right before the PR merges.
• providerId: "default-claude-cli" for portability. Users can override it in their own copy. The default should work for anyone without extra setup.
• No preambles in the output. Write the system prompt so the AI's only job is producing the deliverable. "Here is the result" and similar openers are bugs, not features.

Not sure if something belongs in the defaults? Post it as a Gist or in Discord first. If people want it, then PR it.

---

Tips

• Hotkeys are the fastest way to work. Assign your most-used workflows in Settings → Hotkeys. Selecting text and hitting a key to fix it, tighten it, or expand it is faster than reaching for a menu.

• Lint before Humanize. Run Lint first to fix mechanical errors, then Humanize to clean up the writing style. Both can be chained: enable "Humanize output" on any workflow to get both passes in one step.

• The Humanize workflow is for output only. It runs as a second pass on AI-generated text. Running it directly on your own writing may over-edit your voice.

• Changing the workflows folder renames the vault folder and moves all your files automatically. The new path takes effect immediately.

• Reload the plugin to pick up new direct commands after adding workflow files. The workflow picker and settings panel update in real time, but the command palette requires a plugin reload.