# AI Terminal for Obsidian

Chat with an AI assistant (**Claude Code** or **Antigravity**) inside Obsidian, right next to your notes. The AI
can read your notes and edit them for you.

> **Note**: **macOS only** (Obsidian desktop v1.13+). Windows, Linux, and mobile devices (iOS/Android) are not supported.

## What is this?

[Obsidian](https://obsidian.md) is a free note-taking app. AI Terminal is a **plugin**, a small add-on that gives
Obsidian a new feature: a chat panel where you talk to an AI about your notes.

You type a request in plain words, and the AI does it in your notes. For example:

- "Summarize the note I have open in five bullet points."
- "Make 10 quiz questions from my Biology lecture notes."
- "Fix the spelling and grammar in the selected text."
- "Find every note that mentions the French Revolution and make a list of links."
- "Turn this messy list into a table."

You do not need to know how to program. The panel looks like a "terminal" (a black window with text), but you
just type normal sentences and press Enter.

Features:

- **AI panels in Obsidian.** Claude Code, Antigravity or a shell open as panels, like any other tab.
- **Context from the editor.** The AI can see the open note and the selected text.
- **Live updates.** Notes the AI edits change in Obsidian right away.
- **Paste screenshots.** Press Cmd+V to attach a screenshot to Claude Code or Antigravity.
- **Undo for AI changes.** A copy of your notes is saved before each message to the AI, so you can undo its changes.

### Words you will see

| Word | What it means |
| --- | --- |
| **Vault** | The folder where Obsidian keeps your notes. |
| **Plugin** | An add-on that gives Obsidian new features. This is one. |
| **Terminal** | A Mac app (in Applications › Utilities) where you type commands. You need it a few times during setup. |
| **Claude Code** | An AI assistant made by Anthropic. |
| **Antigravity** | An AI assistant made by Google. Its command is `agy`. |
| **Shell** | A plain terminal, without AI. You do not need it to use the AI. |

You only need **one** of the two AI assistants. Pick whichever you have an account for.

## Before you start

You need:

1. **A Mac** with the **Obsidian desktop app**, version 1.13 or newer.
   To check: in Obsidian, open **Settings › About**.
2. **An account for one AI assistant.**
   - **Claude Code** needs a paid Claude plan (Pro or Max) or Anthropic API credits. The free Claude plan does not work.
   - **Antigravity** needs a Google account.
3. **About 15 minutes** for the setup below.

The plugin itself is free. Any cost comes from the AI company's plan.

## Setup

### Step 1: Install Apple's command line tools

The plugin needs two small programs (Python and git) that come with Apple's command line tools.

1. Open the **Terminal** app. (Press Cmd+Space, type `Terminal`, press Enter.)
2. Copy this line, paste it into Terminal and press Enter:

   ```sh
   xcode-select --install
   ```

3. A window opens. Click **Install** and wait until it is done (a few minutes).
   If Terminal says the tools are **already installed**, that is fine. Go to step 2.

### Step 2: Install an AI assistant

Install **one** of these (or both), using its official guide:

- **Claude Code**: [install guide](https://code.claude.com/docs/en/setup)
- **Antigravity CLI**: [install guide](https://antigravity.google/product/antigravity-cli)

The guide gives you a line to paste into Terminal, like in step 1.

To check that it worked, type this in Terminal and press Enter:

```sh
claude --version
```

(For Antigravity, type `agy --version`.) You should see a version number, such as `2.1.0`.
If you see "command not found", close Terminal, open it again and try once more.

### Step 3: Install the plugin

**From Obsidian** (once AI Terminal is in the community plugin list):

1. In Obsidian, open **Settings › Community plugins**. If **Restricted mode** is on, turn it off.
2. Click **Browse**, search for **AI Terminal**, click **Install**, then **Enable**.

**By hand** (works now, without the community list):

1. Open the [latest release](https://github.com/hyunho058/obsidian-ai-terminal/releases/latest). Under **Assets**,
   download these three files: `main.js`, `manifest.json` and `styles.css`.
2. In Obsidian, open **Settings › Community plugins**. If **Restricted mode** is on, turn it off.
3. Next to **Installed plugins**, click the **folder icon**. Finder opens the plugins folder of your vault.
4. In that folder, make a new folder named `ai-terminal` and move the three files into it.
5. Back in Obsidian, click the **reload icon** next to **Installed plugins**. Then turn on **AI Terminal**.

If step 3 does not open a folder: open your vault folder in Finder and press Cmd+Shift+. (period) to show hidden
folders. Open `.obsidian`, and make a folder named `plugins` in it if there is none. Then continue with step 4
inside `plugins`.

### Step 4: First start

1. Click the **terminal icon** in the left ribbon (the thin bar of icons on the far left) and pick
   **Claude Code** (or **Antigravity**). A panel opens on the right.
2. The first time, you see a few questions:
   - "Enable AI session snapshots for this vault?" → click **Enable**. This turns on undo for AI changes.
   - The AI asks you to sign in → follow the steps. A browser window may open.
   - The AI asks if you trust the folder → choose **Yes**.
   - macOS asks "“Obsidian” would like to access files in …" → click **Allow**.
3. Type your question in the panel and press Enter. That's it.

When the AI wants to change a file, it may ask first. Read the question and pick **Yes** or **No**.

## How to use

### Your first request

Try this once to see how it works:

1. In Obsidian, open a note, for example your lecture notes.
2. Click the **terminal icon** in the left ribbon and pick **Claude Code** (or **Antigravity**).
   The panel opens on the right, next to your note.
3. Click into the panel, type this and press Enter:

   ```text
   Add a summary of 5 bullet points at the top of the note I have open
   ```

4. The AI reads your note and tells you what it plans to do. Before it changes the note, it asks for permission.
   Read the question and pick **Yes** (or **No** to stop).
5. The summary appears in your note right away.
6. Not happy with it? Type a follow-up in the panel, such as "make it shorter", or put the note back with
   [Undo AI changes](#undo-ai-changes).

You can keep talking in the same panel. The AI remembers the conversation, so you can say "now do the same for
the selected text" without explaining again.

### Everyday tasks

| To do this | Do this |
| --- | --- |
| Open an AI panel | Click the terminal icon on the left, or press Cmd+P and type "AI Terminal" |
| Ask about a note | Click into the note, then ask in the panel: "summarize the note I have open" |
| Ask about part of a note | Select the text, click into the panel and ask: "explain the selected text" |
| Point the AI at a note | Click into the note, press Cmd+P and run "Send note path to terminal". The note's path appears in the panel. Add your question and press Enter |
| Start a new line without sending (Claude) | Shift+Enter |
| Copy / paste | Cmd+C / Cmd+V |
| Paste a screenshot (Claude Code, Antigravity) | Take a screenshot to the clipboard (Cmd+Ctrl+Shift+4), then press Cmd+V in the panel. If the clipboard also has text, the text is pasted. The Shell panel pastes text only |
| Undo what the AI changed | See [Undo AI changes](#undo-ai-changes) |

Panels work like normal Obsidian tabs: you can drag them, split them or move them to another window, and the AI
keeps running. When you restart Obsidian, the panels come back (Claude resumes each panel's conversation; Antigravity resumes its latest session).

### Undo AI changes

Did the AI change something you did not want? You can go back.

1. Press Cmd+P and run **"Restore notes from before an AI session…"**.
2. Pick a time from the list. It shows when it was, which AI, and the start of your message.
3. You see the notes that changed. Untick any note you changed yourself and want to keep.
4. Click **Restore**.

Restored by mistake? Run the command again and pick **"Before restore"**.

Snapshots save your notes only (`.md`, `.canvas` and `.base` files), not images, PDFs or settings.
They stay on your Mac, outside the vault.

## Safety

- **Do not type in a note while the AI is editing it.** One of the two changes can be lost. Keep Obsidian's
  **File Recovery** on (Settings › Core plugins). It keeps older versions of each note.
- **Your notes go to the AI company.** Notes and text the AI reads are sent to Anthropic (Claude Code) or
  Google (Antigravity), like everything else you send to these tools. Do not use it on notes you must keep private.
- **Read the AI's permission questions.** The AI can also change files that snapshots do not cover
  (images, settings, files outside the vault).
- **Snapshot history restarts after a vault move.** Moving or renaming the vault folder starts a new, empty history.
- **The plugin's own connection is local.** The link between Obsidian and the AI panels works only on your Mac and
  is locked with a key that changes every time. Other computers cannot reach it.
- **Clean up after you uninstall.** If you used Antigravity, open Terminal and run `agy mcp remove obsidian`.
  Obsidian cannot tell the plugin that it was removed, so the plugin cannot do this itself.
  See the [full clean-up steps](docs/user-guide.md#safety).

## Common problems

- **"Command not found: claude"**: Obsidian cannot find the AI program. In Terminal, run `which claude`
  (or `which agy`). Copy the path it prints, for example `/Users/you/.local/bin/claude`, into
  Settings › AI Terminal › Profiles › "Claude Code command" (or "Antigravity command").
- **"Python 3 not found"**: install Apple's command line tools (see [Step 1](#step-1-install-apples-command-line-tools)).
  If you already have Python 3, put its path (from `which python3`) into Settings › AI Terminal › Terminal › "Python path".
- **macOS blocked access** ("Operation not permitted"): open System Settings › Privacy & Security ›
  Files and Folders › Obsidian and turn on the folder of your vault. Then open a new panel.
- **A message says "Reload the plugin"**: in Settings › Community plugins, turn **AI Terminal** off, then on again.
  This closes the open panels.
- **Antigravity does not show the note name near its input box**: this is normal. Ask about "the note I have open",
  or run "Send note path to terminal".

For more, see [Troubleshooting](docs/user-guide.md#troubleshooting) in the user guide.

## Questions

**Does it cost money?** The plugin is free. Claude Code needs a paid Claude plan or API credits. Antigravity needs
a Google account; see Google's page for its limits.

**Does it work on Windows, iPhone or iPad?** No, only on a Mac.

**Do I need to know how to code?** No. You only paste a few lines into Terminal during setup. After that, you type
normal sentences.

**Can the AI break my notes?** It can change or delete notes when you ask it to, or when it misunderstands you.
That is why it saves a copy before each message (see [Undo AI changes](#undo-ai-changes)), and why it asks before
many changes.

**How do I remove it?** In Settings › Community plugins, click the trash icon next to AI Terminal. If you used
Antigravity, also see "Clean up after you uninstall" under [Safety](#safety).

## What the plugin uses and accesses

Obsidian asks plugins to say this clearly. In short: no payment, no ads, no telemetry, and the plugin itself never
connects to the internet.

- **Account.** The plugin is free and needs no account. The AI tools need their own: Claude Code needs an
  Anthropic account with a paid plan or API credits, Antigravity needs a Google account.
- **Network.** The plugin runs a small server that only your own Mac can reach (`127.0.0.1`, locked with a key). The
  AI tools in its panels use it to read the open note and the selection. The AI tools themselves connect to their
  companies (Anthropic, Google) and send what you ask and the notes they read — the same as when you use them in
  Terminal.
- **Files outside your vault.** The plugin needs these to run the AI tools and to keep the undo history out of
  your vault:
  - `~/.config/obsidian-ai-terminal/`: small helper scripts that the AI tools run (they come with the plugin, nothing
    is downloaded) and a lock file.
  - `~/.local/share/obsidian-ai-terminal/`: the snapshot history for [undo](#undo-ai-changes).
  - `~/.claude/`: while "Claude IDE connection" is on, a connection file in `~/.claude/ide/` lets Claude Code
    see your selection. The plugin also reads Claude Code's settings (to give a tip about diffs) and its conversation
    files (to continue a conversation after a restart).
  - Antigravity: while "Antigravity bridge" is on, the plugin adds an `obsidian` entry to Antigravity
    (`agy mcp add`) and the rule `mcp(obsidian/*)` to `~/.gemini/antigravity-cli/settings.json`, so Antigravity
    can use the note tools without asking each time.
  - Your shell settings (such as `~/.zshrc`) are read by starting your login shell, so the AI tools find the same
    programs as in Terminal.

## More

- [User guide](docs/user-guide.md): every feature and setting, what the AI can see, where snapshots are saved,
  known limitations.
- [Development](docs/development.md): build from source, the in-app test checklist, running the tests, releasing.

## License

[MIT](LICENSE)