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
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.
- Open Settings → Community plugins in Obsidian. If Restricted mode is on, turn it off.
- Press Browse, search for “BRAT”, install it, and press Enable.
- Open Settings → BRAT → Add Beta plugin.
- Enter
koooyooo/angel-and-devil-obsidianas the repository and add it (the latest version is fine). - Turn on Angel & Devil under Settings → Community plugins.
BRAT takes care of updates from then on.
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.
- Download
angel-and-devil.zipfrom the latest release. - Extract the zip.
- Windows: right-click the zip → Extract All
- macOS: double-click the zip
angel-and-devilwith three files in it:main.js,manifest.json, andstyles.css. - In Obsidian, open Settings → Community plugins and press the folder icon next to “Installed plugins”. This opens the plugins folder (
<vault>/.obsidian/plugins/). - Move the whole
angel-and-devilfolder 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 - 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.
- Open the API key page in Google AI Studio, sign in with your Google account, and press Create API key.
- In Obsidian, open Settings → Angel & Devil, paste the key into Gemini API key, and press Save.
- Press Check key. When you see “The key works.”, you are ready.
Recommended for using the key safely
- Create a dedicated key for this plugin (if it leaks, you can delete just that key).
- In Google Cloud Console → Credentials, restrict the key to the Generative Language API only.
- Set a monthly spend cap in Google AI Studio → Spend and a budget alert in Cloud Billing → Budgets & alerts.
Where the key is stored, and whether other plugins can read it, is explained in Disclaimer & privacy.
Your first banter
- Open the note you want them to read: a daily log, book notes, anything.
- 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.
- 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.
Recommended settings
Both are off by default, but we recommend turning them on. You find them under Settings → Angel & Devil.
Remember bantersRecommended
After every banter, the angel and devil each leave a memo and rewrite their impression of you. Later banters build on them: the pair can refer back to earlier talks and stops repeating a point it has already made. It gets better the longer you use it — this is the one we recommend most.
- Memos and impressions come back in the same request as the banter, so there are no extra Gemini calls (the request just gets a little longer).
- While it is on, the latest memos (up to 10) and the impressions are sent to the Gemini API together with your note.
- Memory is kept as ordinary notes in a vault folder (default
_angel_and_devil/). You can read, edit, or delete them.
Enable read aloudRecommendedMind the cost
The angel and devil read the banter in two different voices, and the characters move along with them. A 🔊 button appears in the banter window.
- Generating audio (Gemini TTS) can cost more than text. Check Google's pricing.
- That is why you are asked before every read-aloud (Confirm every time, on by default). Replaying the same banter uses a cache and costs nothing.
- The banter itself (text) may also be billed once you go beyond Google's free tier. Charges go to your Google account.
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.jswill not load). - Check that
manifest.jsonis 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”
- You hit the free tier's rate limit or your own spend cap. Wait a moment, or check Google AI Studio → Usage.
I want it on my phone
- A manual install is hardly possible on mobile. Use option 1 (BRAT).
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.