Getting started

Getting started

From installing the Obsidian plugin and setting up a Gemini API key to your first banter. It takes about ten minutes.

Requirements

  • Obsidian 1.8.7 or later (Windows / macOS / Linux / iOS / Android). Storing the API key in Obsidian's secret storage needs 1.11.4 or later.
  • A Google account (to create a Gemini API key).

Angel & Devil is not in Obsidian's community plugin directory yet, so searching for it in Obsidian's settings will not find it. Use one of the options below.

Install

Recommended

Option 1: BRAT

BRAT is a community plugin that installs beta plugins from GitHub and keeps them up to date. It works entirely inside Obsidian, on Windows, macOS, Linux, iOS, and Android.

  1. Open Settings → Community plugins in Obsidian. If Restricted mode is on, turn it off.
  2. Press Browse, search for “BRAT”, install it, and press Enable.
  3. Open Settings → BRAT → Add Beta plugin.
  4. Enter koooyooo/angel-and-devil-obsidian as the repository and add it (the latest version is fine).
  5. Turn on Angel & Devil under Settings → Community plugins.

BRAT takes care of updates from then on.

Without BRAT

Option 2: Manual install

For people who would rather not install another plugin (BRAT). Do this on a computer (Windows / macOS / Linux). To update, repeat the same steps for each release.

  1. Download angel-and-devil.zip from the latest release.
  2. Extract the zip.
    • Windows: right-click the zip → Extract All
    • macOS: double-click the zip
    You should get a folder named angel-and-devil with three files in it: main.js, manifest.json, and styles.css.
  3. In Obsidian, open Settings → Community plugins and press the folder icon next to “Installed plugins”. This opens the plugins folder (<vault>/.obsidian/plugins/).
  4. Move the whole angel-and-devil folder into it. The files should end up here:
    <vault>/.obsidian/plugins/angel-and-devil/main.js
    <vault>/.obsidian/plugins/angel-and-devil/manifest.json
    <vault>/.obsidian/plugins/angel-and-devil/styles.css
  5. Back in Obsidian, press the reload icon next to “Installed plugins”, then turn on Angel & Devil (turn off Restricted mode if it is on).

Can't find the folder? .obsidian starts with a dot, so macOS Finder hides it. Press Cmd + Shift + . in Finder to show it. Windows File Explorer shows it as usual. If there is no plugins folder yet, you can create it yourself.

Option 3: Install script (macOS / Linux, for developers)

For people comfortable with a terminal. It downloads the three files from the latest release straight into your vault; your settings (data.json) are kept on updates. It does not work on Windows (use option 1 or 2).

curl -fsSL https://raw.githubusercontent.com/koooyooo/angel-and-devil-obsidian/main/install.sh \
  | sh -s -- /path/to/your/vault

To pick a version, pass it as the second argument (for example … | sh -s -- /path/to/your/vault 0.2.2). Then turn on Angel & Devil under Settings → Community plugins.

Set up a Gemini API key

The banter is written by Google's Gemini API, called with your own Gemini API key. Nothing goes through a server run by the author.

  1. Open the API key page in Google AI Studio, sign in with your Google account, and press Create API key.
  2. In Obsidian, open Settings → Angel & Devil, paste the key into Gemini API key, and press Save.
  3. Press Check key. When you see “The key works.”, you are ready.

Recommended for using the key safely

Where the key is stored, and whether other plugins can read it, is explained in Disclaimer & privacy.

Your first banter

  1. Open the note you want them to read: a daily log, book notes, anything.
  2. Press the 😇😈 button in the note header (top right). You can also use the ribbon icon on the left or the command “Angel & Devil: Start banter” in the command palette.
  3. Click, tap, or press Space to advance one line at a time. Skip shows everything, Again regenerates, and Save to end of note keeps it in the note.

Select some text first to have them read only that part. After the banter you can also say one thing back in the box below it.

Troubleshooting

Angel & Devil does not show up in the community plugins list

  • Check that the folder is not nested one level too deep (plugins/angel-and-devil/angel-and-devil/main.js will not load).
  • Check that manifest.json is in the folder, then press the reload icon next to “Installed plugins” or restart Obsidian.
  • Check that you used the right vault (each vault has its own .obsidian).

I can't find the 😇😈 button

  • Make sure a Markdown note is open. With the plugin on, you can also start from the ribbon icon or the command palette.

“The API key looks invalid”

  • Check for extra spaces around the key, paste it again, then press Save → Check key.
  • If you restricted the key, make sure the Generative Language API is allowed.

“Usage limit reached”

I want it on my phone

Still stuck? Let us know in GitHub Issues (never paste your API key).

Update & remove

  • Installed with BRAT: updates are automatic.
  • Installed manually: overwrite the three files with the new release, then turn the plugin off and on again. Your settings (data.json) are kept.
  • Remove: press Uninstall under Settings → Community plugins. To remove the API key too, press Delete under Settings → Angel & Devil first. If you used memory, its folder (default _angel_and_devil/) stays in your vault as ordinary notes; delete it by hand if you no longer need it.