Glossa

Your vault, in context. Your edits, under control.

A local-first AI workspace for reading, researching, and changing real notes without losing sight of the source.

中文说明 · Latest release · Changelog

Glossa turns the sidebar into a working surface, not a separate chatbot. The active note can enter context automatically, explicit attachments stay grounded as the task target, and API file changes follow visible tool and approval rules. Optional local CLI runtimes use their own native permissions, as described below.

Install · Quick start · Background chats · Models and CLI · Upgrade guide · Privacy

What Glossa Does

Temporary chat

Ask a side question about part of an answer without adding it to the main conversation. Select text in the conversation, right-click and choose Add to temporary chat, or use the bubble-plus button under a message (it quotes the selection, or the whole message when nothing is selected). Glossa: Open temporary chat in the command palette reopens it.

• Opens in a separate window of about 560 × 740, so the main sidebar stays readable; a tab is the fallback. Each main chat has its own temporary chat, and later quotes from the same chat join it.
• The window holds only the quotes, the conversation and a question box. Save as note and Clear sit in its title bar; its ⋯ menu also opens the source chat and, when you have more than one API endpoint, switches the model.
• Quotes wait above the question box, one line each (click one to read all of it), then stay attached to the question they were asked with. Formulas are quoted as their LaTeX source, and code, lists and tables keep their Markdown structure; selecting a whole message quotes its original text.
• Each question sends only its quotes (with the question each quoted reply answered) and the earlier turns of this temporary chat. Nothing else from the main chat goes along: no other messages, notes, attachments, tool results or reasoning. When a long discussion would overflow the model's context, the oldest turns are left out and a line in the window marks where.
• Answers come from an API endpoint: the main chat's, or your first API endpoint while the main chat uses Codex, Claude Code or Grok. There are no tools, vault access or CLI sessions. Replies follow the language of your question, stream as rendered Markdown with math and code, and keep model reasoning folded. Esc stops a reply; a failed or stopped reply can be retried, and the last answer regenerated. A failed or stopped regeneration keeps the previous completed answer.
• Place in main composer, under each answer, puts that reply into the source chat's composer, switching to that chat if needed; it is never sent automatically. Save as note writes the discussion, with its quotes, to a Markdown note in your chats folder. It saves a snapshot taken when you click and retains any output-limit warning.
• Up to 8 quotes and 24,000 characters per question; a single quote is cut at 12,000 characters, and Glossa tells you when that happens. A temporary chat holds up to 50 turns.
• Closing the window stops a reply in progress; received text and an unsent draft stay available until Obsidian restarts or Glossa is disabled. Content lives only in memory, and windows restored from a saved layout close themselves. Temporary storage does not change your API provider's retention policy.

The question rail now follows the turn being read, including the bottom of a long final answer. Positions are recalculated after Markdown rendering, folding and window resizing.

Agent improvements in 1.2.0

1.2.0 — October 26, 2026 adds the temporary discussions above and the following Agent improvements. Existing API/CLI workflows are retained; native Codex sessions and idle compaction are opt-in. Source type checks now run without unsafe-value exemptions.

• Recover interrupted runs clearly. Each turn records ordered, bounded status events. Reopening a chat preserves completed results and marks unfinished operations as interrupted; it never automatically repeats a file write.
• Resume native Codex threads. Enable Native Codex sessions in the Codex endpoint’s advanced settings. This optional App Server mode keeps a thread across messages and restarts, and adds Glossa’s instructions to Codex’s own. Changed history, forked chats, working directories, permission modes or Glossa instructions (for example a new day or edited project instructions) start a fresh thread. Use Reset connection in chat to detach it. Failed turns are not replayed automatically; turning the setting off keeps the existing CLI workflow.
• Verify skills against files. In Learned skills → draft → File operation tests, provide sample Markdown files and exact expected contents. Baseline and candidate each operate on fresh temporary files using read, list, edit, write and rename tools. repeat: true checks the same task twice; unchanged files, YAML and links can be checked exactly. Expected contents stay local. This requires an API endpoint with tool calling and can make multiple model calls. It does not exercise Obsidian’s automatic link updates or other plugins. A skill with file examples must pass both text and file checks before activation or restoration.
• Control forked skill subtasks. Skills with context: fork show their status, tools, step count and recent output. Stop one subtask or add an instruction for its next model step. Children inherit Plan/Act mode, workspace boundaries and approval rules. Stopping keeps completed changes, and restarting does not silently resume unfinished children.
• Optionally compact while idle. Enable Compact during idle cache window and enter your API provider’s documented Prompt cache lifetime (seconds). After a successful turn with at least 100,000 reported input tokens, Glossa can make one summary request near expiry, preserving the last request prefix where supported. Typing, pending messages and running tasks prevent it. Unknown cache lifetimes, CLI conversations and requests with latest-user image attachments are skipped. It adds a model call and does not guarantee cache hits, lower cost or a lossless summary. Existing manual and pressure-based compaction remain available, with undo and protection against applying a summary to changed history.

Native Codex conversations are also stored by Codex itself. File evaluation uses private .glossa/evaluations/ directories and removes each run’s directory on normal completion, failure or cancellation; a host crash may leave a fixture directory. See Privacy & data flow for storage and request details.

Previous release: 1.1.0

1.1.0 — October 20, 2026 adds background conversations, per-chat history files, folder operations and model-aware reasoning controls.

• Keep several conversations moving. Switch chats, start a new one or close the panel while a response continues. History shows which chats are running or waiting for approval; notifications take you back to the relevant chat.
• Keep more history with less rewriting. Chats are saved individually, loaded when opened and no longer limited to the 100 most recent. Search uses a bounded preview of your questions and the answers, excluding attached source text.
• Organize files as well as conversations. Create empty vault folders, move or rename folders, and send files or whole folders to Obsidian's configured trash. Eligible text files can be restored from the turn's change summary.
• Choose reasoning that fits the model. Recognized official API endpoints show model-specific levels and defaults. Compatible gateways retain flexible effort values. Each OpenAI-compatible endpoint also has an automatic, fixed or omitted temperature setting.
• Read clearer replies. More interface text follows your language, Markdown spacing is tighter, leading thinking blocks appear in the reasoning card, and code blocks use Obsidian's native copy button.
• Keep parallel work separate. Skill approval scopes belong to their own run, writes to the same note are serialized, and stopping a waiting task prevents its pending file change.

Requirements: desktop Obsidian 1.12.0 or newer. Existing API endpoints and model choices are retained. See Upgrading and local history before upgrading, and the full changelog for details.

Install

Plugin Marketplace

Open Settings → Community plugins → Browse, search for Glossa, then install and enable it.

Open Glossa in the plugin marketplace

GitHub Release

Download main.js, manifest.json, and styles.css from the latest release, then place them in:

<your-vault>/.obsidian/plugins/glossa/

Reload the app and enable Glossa under Community plugins.

Start in a Minute

1. Open Glossa from the ribbon or command palette.
2. Add an OpenAI-compatible, Anthropic-compatible, or local HTTP model endpoint.
3. Open a note, attach a file with @, or select text.
4. Ask directly. Stay in Plan for read-only work; switch to Act when you want file changes.
5. Review approvals before writes or downloads.

Custom API compatibility

For Anthropic-style endpoints, enter an SDK root such as https://api.minimax.io/anthropic, a versioned root ending in /v1, or a full Messages URL. Glossa displays the final request URL and uses the same path rules for chat, connectivity testing, and model discovery. OpenAI-compatible endpoints still use their versioned root.

Under an endpoint's Advanced → Extra JSON body, enter a JSON object such as {"reasoning_split":true} (MiniMax OpenAI format) or {"thinking":{"type":"disabled"}} for models that support disabling thinking. Explicit parameters replace generated values at the top level, including thinking, sampling, and token limits. Model, messages, system, tools, tool selection, and stream fields are reserved. Invalid input stays unsaved with a validation message; clear the field to remove overrides. Extra body values are stored in plugin settings as ordinary configuration, so use the API key field for credentials.

Reasoning labels follow the chosen model. Default leaves the provider in control; Thinking off is shown when Glossa has a matching disable setting. Some models always reason or have no adjustable depth. Translation and inline completion choose the lightest supported reasoning setting; this does not guarantee that thinking can be disabled.

Quick translation gives MiniMax M2.x an output limit of 16,384 tokens to leave room for thinking. This is a maximum, not a fixed charge or a guarantee of completion; explicit extra-body token limits take precedence. Thinking-only and truncated Anthropic responses display an error with a Retry button instead of a completed translation. In Auto mode, each new eligible selection is sent to your configured translation endpoint; turn Auto off to require a manual action.

Typical Workflows

Open a paper
  -> ask for the method or a figure
  -> Glossa chooses text pages or visual evidence
  -> answer stays grounded to page-level content

Name a public paper and a vault folder
  -> bounded source discovery
  -> title and response validation
  -> save the real PDF
  -> inspect the downloaded paper

Request a note change
  -> read only the relevant source
  -> preview and approve the edit
  -> write the smallest patch
  -> verify the changed region

Context That Behaves Naturally

• The active Markdown note is refreshed when the request is sent.
• A named attachment or explicit selection is treated as the primary target.
• Source language and response language are separate, so an English paper does not override a Chinese request.
• Long chats keep recent evidence complete, compact older tool output, and preserve corrections, URLs, paths, failures, and next actions.
• Persisted chat data strips repeated image payloads and model-only context while keeping useful text and metadata.

Conversations and background work

• Organize history: click + below history search to create a conversation folder, then use a chat's ··· → Move to folder. Renaming or removing these folders does not move or delete vault notes; removing a folder keeps its chats unfiled.
• Run more than one chat: switch chats or close the Glossa panel after sending. The active run continues while Obsidian and the plugin remain enabled. Reopen history to see running and approval states; the history button counts background runs.
• Approve in the right chat: a background chat waits when approval is needed. Open it from history or its notification to review the operation. Closing the panel does not approve a request.
• Steer or queue: while an API chat is running, Enter supplies text to its next model step. Use the composer menu to queue the next turn instead; CLI follow-ups always queue. Up to 20 text messages can wait, and pending messages can be edited or removed. Queues scheduled during a run continue when you switch chats or close the panel. Stop ends continuation; after restarting Obsidian, pending messages require a manual send.
• Set a bounded task: use the header's ◎ button and Resume. Tasks keep their objective, progress and blockers, with 1–20 rounds (default 3). They can continue in the background; errors, blockers and the round limit stop continuation. Restored tasks require explicit resume. This feature requires a tool-enabled API endpoint.
• Stop deliberately: use Stop in the chat to cancel its run and further queued/task continuation. Quitting Obsidian or disabling the plugin also stops runs. Already completed file changes remain recorded.
• Export diagnostics: the export menu downloads up to 500 metadata events, including model, tool sequence, duration and error codes. It excludes prompts, note content, tool arguments, paths, endpoint URLs and credentials, and is never uploaded automatically.

Models, reasoning and local CLI

File references stay on the left; the compact selector on the right follows API / CLI → provider or CLI app → model.

Install and sign in to the CLI in your terminal first; Glossa does not install, update or authenticate it. Detection checks standard executable locations; set an explicit binary path under Providers if needed. Selecting CLI reads its native model catalog and per-model effort levels. Returning from API restores the last CLI provider and its choices. Catalogs are cached for 10 minutes, can be refreshed from the model menu, and remain available after a failed refresh. An empty model uses the CLI default. Global/per-endpoint proxy settings apply without reading shell startup scripts.

CLI requires a desktop filesystem vault and runs from the vault root. Codex uses its native read-only or workspace-write sandbox. Claude Code requires --restricted support and exposes Read/Glob/Grep, plus Edit/Write for writable Act mode. External MCP configuration is disabled for Codex and Claude Code. Grok requires streaming-messages-json support, requests its native read-only/workspace sandbox and limits built-in tools to read/search plus search_replace in writable Act mode; built-in shell and subagents are excluded. No CLI enables permission bypass. Native configuration, sandbox support and provider terms still apply; Grok continues to load its local configuration.

CLI actions use the CLI's own permissions. They do not use Glossa's per-tool approvals, workspace-subfolder restrictions, learned skills or undo checkpoints. Keep your own file history for important changes. CLI supports text and note context; use API mode for images. Conversations remain available for folders and export.

Vault file and folder operations

In API mode, keep Plan for reading. To change files, select Act with writable permissions and describe the intended operation, for example:

• “Create an empty Research/Reading folder.”
• “Move Inbox/Papers to Research/Papers.”
• “Move Drafts/Old and its contents to the trash.”

Writes follow your approval rules. Deletions use Obsidian's configured trash location; the vault root and configuration directory are protected. Inspect the turn's file change summary for results and eligible undo actions. Text snapshots cannot fully restore moves, renames or binary files, and large operations can exceed the snapshot limits. Use file recovery or your backups when undo is unavailable.

Upgrading and local history

1. Update through Obsidian, or replace only main.js, manifest.json and styles.css with the files from the same release. Keep your existing settings and history files.
2. On first load, Glossa migrates the old single-file history to chats/<id>.json, with chats.json holding folders, summaries and search previews. It retains the old store until every chat is written and retries an incomplete migration.
3. A migration copy, chats.v3-backup.json, is kept for 30 days. It can recover missing chat files while available. Deleting a chat also removes its copy from this backup; clearing all chats removes the backup.

These files live under the configured plugin directory, normally .obsidian/plugins/glossa/. Chat history, previews, pending messages and task state are plain text and may be included in vault sync. API-key encryption does not encrypt chat history. Keep a separate backup before upgrading or downgrading; older versions do not understand the new per-chat storage format. The migration copy is a temporary recovery aid, not a permanent backup.

Learned skills

Learn from a correction. Use Remember this correction beside an assistant reply to turn feedback into an editable skill draft. Choose an existing learned skill to improve it, or create a new one. Review the conversation excerpt and workflow diff, then inspect the generated examples or add your own. Each example runs with fresh context against both the candidate and the currently enabled version (or no skill), checking exact output fragments and whether the skill should apply. Editing the draft or examples invalidates the results; every candidate example must pass before you can enable it. Tied scores are shown as no measured gain.

Text validation checks text behavior using 3–5 examples, with two model calls per example. Optional file validation executes tools only against isolated sample Markdown files, using fresh baseline and candidate fixtures; existing notes are not modified. Generation uses the selected chat model. The model does not receive the expected output checks. Review the excerpt before sending it; tool result bodies and automatic attachment contents are not collected by the learning feature. There is no background training or model-weight update.

Use Glossa: Manage learned skills or Learning history in the dialog to inspect results, disable a skill, edit a draft, or restore a previously tested version. Enabled skills join normal skill discovery for future turns and keep the existing tool approval rules. Built-in and manually authored skills are not overwritten. Drafts, workflow versions, feedback references, model identity and validation outputs are stored locally in .glossa/learning.json, with up to 12 versions per skill and 60 learned skills. Learning history is plain text and can be included in vault sync; API-key encryption does not encrypt this file. Simultaneous edits are checked before saving. Historical validation results describe the model and examples used at that time.

Accounts, network use and local files

Glossa is free and does not require a Glossa account. Cloud model and search providers may require their own account, API key, subscription or usage payment; those charges are paid to the provider. A local HTTP model endpoint can be used instead.

Local CLI use accesses installed executables outside the vault; your home directory is used to locate common executable paths. Grok requires a prompt file, so Glossa writes the conversation and selected context to a private glossa-grok-* directory in the OS temporary folder outside the vault (owner-only file permissions on POSIX). It deletes this temporary directory after completion, failure or cancellation; an abrupt host crash may leave it behind. Codex and Claude Code receive prompts over stdin. Glossa does not read CLI credential files; the CLI itself uses its own login, configuration and retention policies.

Safety by Design

• Plan mode and read-only permissions are the conservative starting point.
• Write approvals can be scoped by tool, path, folder, or session.
• Checkpoints snapshot affected files before destructive edits.
• Deleting and moving files or whole folders follows the configured approval rules. Deleted items go to the trash set in Obsidian, and the vault root and configuration folder are never deleted or moved.
• Network tools use bounded responses, redirect checks, private-network blocking, and explicit download intent.
• Validated downloads enforce size limits and file signatures before writing.
• API mode uses vault tools and Glossa approvals. CLI mode explicitly launches an installed local program under the separate boundaries described above.

Glossa itself is not a hosted AI service. Conversation content and selected context are sent to the model endpoint you configure; web content is accessed only for the web action being performed. See Privacy and Security for the exact boundaries.

Build and Verify

git clone https://github.com/yiiwang118/obsidian-glossa.git
cd obsidian-glossa
npm ci
npm run check

npm run check runs TypeScript checks, review and strict lint, directive auditing, an independent community-scanner lint pass, the complete test suite, dependency audit, production build, generated-bundle review scanning, and release metadata validation.

For development builds:

GLOSSA_PLUGIN_DIR="/path/to/vault/.obsidian/plugins/glossa" npm run dev

Project

• Desktop-only in the current release.
• Compatible with app version 1.12.0 and newer; settings search is enhanced automatically on 1.13+.
• New installations default to Plan mode with read-only permissions.
• Release assets are rebuilt and validated by GitHub Actions before publication.
• Issues and focused, reproducible bug reports are welcome.
• This open-source project recognizes the LINUX DO community.

License

MIT © yiiwang