Argus — your second brain, on your machine

A local, Jarvis-style assistant built on an Obsidian vault: chat grounded in your own notes, a unified task + calendar day view, a coursework engine that turns your real lecture materials into cited practice exams, an AI day planner that only ever proposes (you approve every change), and a morning briefing written into your daily note at 07:00. Your vault stays plain markdown you own — delete Argus tomorrow and your second brain stays.

How it works

Next.js dashboard  ←→  FastAPI backend  ←→  Obsidian vault (markdown, single source of truth)
                          │
                          ├─ RAG index (local embeddings — your notes never leave your machine for indexing)
                          └─ agent (suggest-then-approve: nothing is written without your click)
                               └─ your choice of model: local Ollama · a hosted API · Claude

No Claude Code required. Chat, the day planner and study generation run on whichever model you register: a model on your own PC via Ollama, any hosted OpenAI-compatible provider (Groq, Together, Fireworks, OpenRouter…), the Anthropic API on a key, or Claude Code on your existing subscription. Every model is badged LOCAL or HOSTED in the UI, so whether your notes leave the machine is always visible.

Features

• Dashboard (home) — Layout-A command center: morning briefing (collapsible), stat tiles (due/overdue/done/streak/focus hours), an interactive agenda you can check off / edit / delete inline, a GitHub-style productivity heatmap (tasks + notes + study + captures, 52 weeks), quick capture, a recent-activity feed, a Quick Links panel for saving and one-click opening of frequently-used sites (opens in your system browser; https-only), and a docked mini chat — all on one screen, every widget interactive.
• Chat grounded in your vault — every answer carries citations that deep-link back into Obsidian; "that's not in your notes" instead of hallucinations. One shared conversation whether you use the dashboard dock or the full Chat tab.
• Vault edit & delete — edit or delete your own notes and task lines straight from the UI (agenda rows, captured inbox notes, Journal-adjacent notes). Every change goes through the single writer with a git snapshot first (undo is git revert away) and a compare-and-swap check that fails cleanly if the file changed under you. 99-Private/ and 90-Meta/ are always refused, server-side. AI-initiated changes still go through the suggest-then-approve Review queue — direct edit/delete is for changes you make yourself.
• Today's flow — quick capture to 00-Inbox/ (click, or drag a file straight onto a course card on Notebook), and the morning briefing (07:00 job or on-demand): schedule, due/overdue, yesterday's leftovers, exam countdowns, weak topics.
• Planner — type /plan tomorrow in chat; the agent proposes schedule blocks, task edits, and note edits into a Review queue. Approve applies them through a single audited writer (with a git snapshot of the vault first); dismissing with a reason teaches the planner your preferences.
• Notebook — upload or drag-and-drop lecture PDFs/slides, generate study guides and practice exams where every question cites a real page, take them in quiz mode, and let missed topics feed your review queue (and your briefing, and your planner). Flashcard decks you write, paste, import from any note's Q::/A:: pairs or generate from your sources, with four ways to study them — spaced repetition, browsing, adaptive practice and a timed matching game. Opens in a window of its own so a deck can sit beside whatever else you are doing. See docs/notebook.md.
• Tasks — Obsidian Tasks syntax parsed vault-wide into overdue/today/week/someday.
• Insights — task completion trend, overdue chart, calendar load vs focus time, study streak, practice-exam scores per course, the productivity heatmap (full-width), plus your coding-session activity.
• Models — pick any backend per model on System: a guided setup flow (provider → credentials → test connection → save) that never saves an untested configuration, plus a hardware-aware browser of local models that labels each one FITS / SLOW / TOO BIG against your actual RAM and GPU and installs it in one click. Every model must pass a live tool-calling check before it's registered, so citations and planner proposals work the same on every provider.
• Audit — /api/audit lists exactly which vault files each agent prompt read (paths only, never content).

Not a developer? docs/SETUP.md is a step-by-step install guide that assumes no programming knowledge.

Quickstart

Prerequisites: Python 3.12+, Node 18+, git. (Windows: PowerShell works fine for all commands below; there's no gh/uv dependency for the core app.)

git clone <this-repo> && cd <repo>

# 1. Backend
python -m venv .venv
.venv/Scripts/activate          # Windows · use `source .venv/bin/activate` on macOS/Linux
pip install -e ".[dev]"

# 2. Create (or point at) your vault
argus init ./my-vault           # new vault from the template, or set VAULT_PATH in .env
                                 # to an existing Obsidian vault

# 3. Build the dashboard once
cd web && npm install && cd ..

# 4. Run — daily-use production launcher (builds if needed, serves both together)
argus web                       # dashboard on :3000, API on :8000, Ctrl-C stops both

Open http://localhost:3000 — the Dashboard is now the home page — then verify the install:

argus doctor                    # vault, git, db, chroma, keyring, connectors

argus web rebuilds the dashboard automatically the first time (or whenever web/.next is missing); pass --build to force a rebuild after pulling UI changes, or --port/--backend-port to change the defaults.

Optional extras:

pip install -e ".[rag]"         # chat/RAG stack (embeddings, chroma, pdf extraction)
argus reindex                   # build the search index over your vault
argus relink                    # link generated notes into the vault (--dry-run first)
argus connect gcal              # Google Calendar (needs a Desktop OAuth credentials.json)
argus connect todoist <token>   # Todoist personal API token

Both connectors are optional — everything else works without them, and argus doctor reports them as WARN (not FAIL) until you connect them.

Choosing a model

Open System → MODELS → + ADD MODEL and pick a provider. The flow tests the connection — reachable, key accepted, tool calling works — and lists the models the endpoint actually serves before it lets you save.

Provider	What you need	Notes
Ollama on this PC	Ollama running	Free, offline, notes never leave the machine. The LOCAL.MODELS panel recommends one that fits your hardware and installs it in a click.
Hosted API	a key from Groq / Together / Fireworks / OpenRouter / DeepInfra	Fast on any machine — the reason Argus works on a thin laptop, since local inference needs more horsepower, not less.
Anthropic API key	a key from console.anthropic.com	Claude without installing Claude Code.
Claude Code	the CLI installed and signed in	Uses your existing subscription (invariant I5).

API keys go to the OS keyring; .argus/models.json stores only a reference (invariant I4). argus doctor reports Ollama's status as WARN (not FAIL) when it's absent — it's one option, not a requirement.

Registration requires a live tool-calling check to pass. There is no no-tools fallback on any provider: chat's citations and the planner's suggest-then-approve flow are both enforced through tools, so a model that can't call them would look like it was working while quietly breaking both.

Connect your coding agent

argus mcp-server exposes your vault's read-only tools (search_vault, read_note, list_tasks) over MCP, so your own terminal agent can use your notes from any project directory:

# Claude Code
claude mcp add argus -s user -- argus mcp-server

# Codex CLI / Gemini CLI — add to their MCP config:
#   { "mcpServers": { "argus": { "command": "argus", "args": ["mcp-server"] } } }

The planner's propose_* tools are deliberately not exposed: an external agent has none of the in-app planner's context, and anything it queued would land in your Review queue looking identical to a well-informed suggestion.

This needs the source install — the packaged desktop app doesn't put argus on your PATH.

Project layout

backend/        FastAPI app, CLI, storage (Python 3.12, type-hinted, ruff)
web/            Next.js 14 dashboard (TypeScript, Tailwind)
vault-template/ PARA-style vault skeleton copied by `argus init`
tests/          pytest suite
docs/           specs, build state, decision log, phase plans

Inside backend/, the three root modules wire everything together and the packages below them are layered:

main.py       app factory — mounts one router per feature, defines /health
cli.py        the `argus` console script
scheduler.py  the 07:00 briefing and nightly task-cache jobs

core/         settings, model registry, sqlite, nothing feature-specific
vault/        the single write path (I1), its readers, and the privacy policy
telemetry/    token usage and the prompt audit trail
agent/        provider adapters, chat runtime, planner, MCP server
rag/          extract -> chunk -> embed/store -> retrieve
connectors/   Google Calendar, Todoist

features/     one package per feature: briefing, insights, flashcards,
              quick_links, review, study, tasks, system, notes, journal,
              search, ingest, chat — each a router.py plus its own modules

The dependency rule is one-way: a feature may import any package above it, nothing above may import a feature, and no feature imports another. Only the three root modules know about features at all.

Coding-agent dev loop (optional)

The claude-integration/ folder journals your Claude Code sessions into the vault's 90-Meta/ zone and surfaces them on the dashboard's Journal page:

powershell -ExecutionPolicy Bypass -File claude-integration\setup.ps1 -VaultPath "C:\path\to\your\vault"

That installs two session hooks (objective stubs, written even with Obsidian closed) and a /log-session command (narrative writeups on demand). Codex CLI hook support is planned on a follow-up branch. For vault access from your agent, prefer argus mcp-server above; Obsidian's Local REST API plugin is an alternative: claude mcp add obsidian -s user -e OBSIDIAN_API_KEY=<key> -e OBSIDIAN_HOST=127.0.0.1 -e OBSIDIAN_PORT=27124 -- uvx mcp-obsidian.

Privacy

• Indexing, embeddings, and storage are fully local.
• 99-Private/ and any note tagged #no-ai are never indexed and never sent to any model.
• Secrets live in the OS keyring — never in the repo or the vault.
• With a LOCAL model nothing leaves the machine at all. With a HOSTED one, only the excerpts relevant to a question are sent — never the whole vault. The badge is on every model row and in the model picker, so the trade-off is opt-in and visible rather than silent.

Development

Daily use is argus web (above); for active development, run the backend and the Next.js dev server separately so you get hot reload:

uvicorn backend.main:app --port 8000      # API on :8000
cd web && npm run dev                      # dashboard — next dev picks :3000, or the next
                                            # free port if something's already listening

pytest                 # backend tests
ruff check backend tests && ruff format --check backend tests
cd web && npm run lint && npm run build && npm run perf:budget
cd web && npm run e2e  # Playwright end-to-end (dashboard widgets, vault CRUD roundtrip, chat dock)

Conventional commits (feat(scope): …). See docs/BUILD_STATE.md for the current roadmap position and docs/BUILD_LOG.md for decisions.

License

MIT