Athena

Athena

Your Second Brain — in Obsidian.

Athena turns your Obsidian vault into a personal knowledge base that compounds over time. Ingest URLs, papers, GitHub repos, screenshots, and videos; an LLM synthesizes each one into a structured wiki page, cross-references it with what you already have, and keeps the whole graph navigable, searchable, and chat-queryable. Athena bundles Gryphon for the chat surface, so you can ask questions about your knowledge base using the LLM provider of your choice (Anthropic, OpenAI, Google, or a local CLI).

Athena is not affiliated with Anthropic, OpenAI, Google, or Obsidian. References to those services describe what the plugin and its bundled SDKs talk to; they do not imply endorsement.

Features

• kb command set — one verb-driven CLI for everything: ingest a URL (kb add), search (kb search), ask (kb query), reflect on recent journal entries (kb reflect), organize hubs (kb create, kb move, kb merge), prune (kb remove, kb trash, kb purge, kb undo). Available in-vault through Gryphon chat or directly in the terminal.
• Three-layer architecture — immutable raw/ sources, LLM-maintained wiki/ synthesis, and a schema (this repo's CLAUDE.md) that governs LLM behavior. Sources are never modified; wiki pages can be regenerated; the schema is the contract.
• Structured wiki digests — every wiki page has ## Key Findings, ## Methods / Architecture, ## Notable Quotes, and ## Relevance sections derived from the raw source by an LLM you choose. No 50K-character body copies.
• Bidirectional cross-references — when page A links to page B, page B links back. Frontmatter related: for graph view and search; body ## Connections section for human navigation.
• Soft delete with rollback — kb remove and kb merge move files to .kb-trash/ where they stay for 30 days. kb undo restores. kb purge permanently deletes. Even after purge, the original URL is preserved so the source can be recaptured from scratch.
• Self-healing capture pipeline — Web Clipper drops, terminal kb add, and Athena's own kb capture-deep (Playwright-based) all flow into the same ingest path. LinkedIn auto-promotes to the deep-capture path so JS-rendered content lands intact.
• Lint as enforcement — every data inconsistency identified in production becomes an auto-fixing check in kb lint. The lint set is the permanent safety net; LLM instructions are suggestions.
• Chat with your KB — Athena bundles Gryphon. Talk to your knowledge base through the chat panel in your sidebar; Gryphon's built-in security layer protects .git/, .obsidian/, .env, and other dangerous paths/commands even in YOLO mode.

Installation

Via Obsidian's Community Plugins directory — once the submission is accepted, search for "Athena" in Obsidian → Settings → Community plugins → Browse.

Via BRAT (for early access to release candidates) — the Beta Reviewers Auto-update Tool is a community plugin that installs plugins directly from GitHub releases.

1. Install BRAT from Obsidian's Community Plugins directory.
2. Open Settings → BRAT → Add Beta Plugin.
3. Paste polleoai/athena and click "Add Plugin".
4. Enable Athena in Settings → Community plugins.

From source (for contributors):

1. Clone the repo into the parent directory of your Obsidian vault, then symlink or copy the built bundle to .obsidian/plugins/athena/ inside the vault.
2. Run npm install and npm run build:all (the :all variant builds the bundled Gryphon submodule too).
3. In Obsidian → Settings → Community plugins → enable Athena.

Requirements

• Obsidian 1.0.0 or later (desktop only — Athena's terminal kb commands and Python KB engine need a desktop filesystem and Node child-process spawning).
• At least one LLM provider for the bundled Gryphon chat surface:
  • Anthropic API key from console.anthropic.com (default, recommended), or
  • An OpenAI / Google Gemini API key, or
  • A locally-installed claude CLI (advanced opt-in — confirm your intended usage complies with that product's Commercial Terms).
• Optional: Python 3.10+ for the wiki page builder + bulk-regen utilities (see below).

How kb add works

The plugin runs end-to-end synthesis on every supported platform (macOS, Linux, Windows):

1. Capture — fetches the page into raw/<type>/artifacts/{slug}.md
2. Wiki page — bin/lib/wiki_page.py writes a wiki page with frontmatter + Source/Local-Copy line + structure
3. Synthesis (1.1+) — Athena calls the LLM you have configured in Gryphon settings (Claude Code CLI, Anthropic / OpenAI / Google API, or Codex / Gemini CLIs) and rewrites the page body with ## Key Findings / ## Methods / Architecture / ## Notable Quotes / ## Relevance

If synthesis can't run (no LLM configured), the page is still created with a "Pending synthesis" placeholder and you'll see *Synthesis skipped: no LLM provider configured* in the chat reply. Fix it with kb regen <url> once Gryphon is set up.

Wiki page builder needs Python (still)

The wiki-page scaffolding step (step 2 above) is performed by python3 bin/lib/wiki_page.py. As of 1.0.9, the plugin bundle ships Athena's Python sources (bin/lib/*.py + bin/config/athena.default.json) inside the plugin install dir — earlier releases required cloning the full Athena vault. Community Plugins users just need:

• macOS: brew install python (3.10+) or python.org/downloads
• Windows: python.org/downloads — IMPORTANT: check "Add python.exe to PATH"
• Linux: usually pre-installed; python3 --version to verify

Then one-time:

python -m pip install pydantic

Restart Obsidian. kb add runs end-to-end. The 1.2 milestone tracks porting the wiki-page builder to JS so this final Python dependency disappears too.

Power users: clone the full Athena vault

The full polleoai/athena repo carries additional terminal-only kb commands (kb search, kb query, kb reflect, kb merge, etc.), a lint suite (kb lint), and the bundled raw + wiki layers that make Athena a working knowledge base out of the box. Clone the repo and open the cloned directory as an Obsidian vault to use those.

Known limitations

Pages that block browser automation

Sites behind Cloudflare's bot challenge, JavaScript-rendered SPAs that require interaction, and authenticated content (LinkedIn timeline, X.com feed) often return a challenge page instead of the article when captured headlessly. Athena will save the challenge-page content as the raw file in those cases (not what you wanted). Workaround: open the page in your normal browser, use the Obsidian Web Clipper extension to drop a clipping into <vault>/clippings/, and Athena's watcher will pick it up.

Linux: BrowserWindow sandbox can be slow on first try

On Ubuntu (especially 22.04+ with Snap-installed Obsidian under AppArmor), Chromium's sandbox helper sometimes fails to start the renderer for an Electron BrowserWindow. Athena's 15s outer timeout (added in 1.0.3) makes this a graceful 15s fall-through to the <webview> capture path rather than a permanent hang, but the first capture on a fresh Linux install can take up to 15s longer than on macOS / Windows. Subsequent captures usually work normally as the sandbox helper warms up.

Prompt history across Obsidian restarts

Up-arrow recall (Gryphon's terminal-style prompt history) reads from the persisted chat-history.json on Obsidian launch. If you sent a prompt right before quitting Obsidian — especially while a slow operation was still in flight — the persistence may not have flushed yet, and that prompt won't be in the up-arrow walk after restart. The visible chat bubble survives (it's loaded from the same file, which DID save before quit); only the input-history index doesn't see it. Open issue under investigation for 1.1.

How it works — three layers

When you run kb add <url>, Athena fetches the page into raw/, then generates a corresponding wiki/ page with structured sections, then cross-references it against existing pages. The wiki is the layer you read and chat with; the raw layer is the audit trail.

Network endpoints

Athena's plugin runtime makes network calls only through the bundled Gryphon chat surface, which in turn talks to the LLM provider you've configured in Settings → Gryphon:

The terminal kb command set (run outside Obsidian, in a shell) makes additional outbound network calls when the user explicitly invokes them:

• kb add <url> — fetches the URL via curl/wget (any host the user provides). For JS-heavy domains on a known allowlist (github.com, x.com, linkedin.com, youtube.com, arxiv.org, medium.com, etc.) it may launch a sandboxed Chromium via Playwright. The full allowlist is in bin/lib/capture.py.
• kb add with arXiv / HuggingFace / GitHub URLs — may follow canonical-source URLs derived from the captured page (arXiv abstract pages → PDFs, GitHub blob URLs → raw, etc.). This is the auto-discovery path documented in CLAUDE.md as "discover-and-surface, never auto-fetch new ingestion" — discovered sources are queued, not auto-pulled.
• kb report-bug / kb request-feature — opens a GitHub issue on the upstream Athena repo via gh CLI.
• Embedding calls (if configured) — local Ollama at http://localhost:11434 only. Athena never sends embedding requests to a remote service.

Browser-based capture (Playwright) runs with Chromium's security sandbox enabled. The terminal kb commands never navigate to file:// URLs, localhost, or private IPs.

System identity reads

Athena reads the following system properties at runtime, in both the plugin and the terminal path:

• Vault root path (via app.vault.adapter.basePath in the plugin; via the script's working directory in the terminal). Required so the Python KB engine knows where to read/write raw/ and wiki/.
• Operating system family (via Node's process.platform) — only used to choose between macOS-specific paths (launchd) and Linux/Windows fallbacks in scripts/. Not transmitted.
• os.hostname() and os.userInfo() are read by bundled Gryphon for CLI-mode auto-detection (see Gryphon's own README for full disclosure). Athena itself does not read these.
• Environment variables consulted: ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY (Gryphon), ATHENA_DISABLE_PLAYWRIGHT_PROMOTE (test escape hatch for the LinkedIn auto-promote path). All optional; absence falls back to in-app settings.

Privacy and data handling

• All knowledge lives on your local filesystem, inside your Obsidian vault. Athena never uploads your vault contents to any external service.
• LLM calls send page contents (raw source body, wiki page body, or query context) to your configured provider — that's the cost of using an LLM. If you don't want a third party to see specific pages, don't add them to the KB, or use the local CLI provider mode.
• .kb-trash/ is local-only; nothing leaves your machine when you delete.
• Per-machine plugin state — data.json (API keys) and chat-history.json* for both Athena and Gryphon are gitignored. They never enter the repo.
• No telemetry by default. kb report-bug only sends data when you explicitly run it, and shows you the payload before transmission (see CLAUDE.md operating principle #6 for the data-integrity feedback loop spec).

Build from source

git clone --recurse-submodules https://github.com/polleoai/athena.git
cd athena
npm install
npm run build:all     # builds bundled Gryphon plugin too, then Athena's bundle

Build outputs land in .obsidian/plugins/athena/:

• main.js — Athena's plugin bundle (~1.3 MB, includes Gryphon)
• manifest.json — plugin manifest
• styles.css — bundled stylesheet (sourced from Gryphon — Athena adds none of its own)

To pre-flight a release, run scripts/release-smoke-test.sh. The --fresh variant clones into /tmp first so it exactly mirrors what Obsidian's submission scorecard sees.

Author

POLLEO.AI

License

See LICENSE if present. Bundled Gryphon retains its own license (see vendor/gryphon/LICENSE).