Your workday "OS"

---

Who this is for

• Dev and design agency owners juggling 5+ client repos, scattered notes, and back-to-back meetings with no time to connect the dots
• Solopreneurs and indie hackers who live in Obsidian but lose hours tracking where their attention actually goes
• Technical founders who want AI-assisted clarity on their own work — without sending their notes, commits, or calendar to a cloud service

If you've ever opened your laptop in the morning and genuinely not known where to start, this is for you.

---

The problem

Your work lives in multiple places that never talk to each other: your notes, your code repos, your recent git activity, your calendar, and the reminder systems wrapped around them. You context-switch constantly, lose track of which projects are getting too much attention (and which aren't getting enough), and spend the first 30 minutes of every day reconstructing what you were doing yesterday.

AI assistants could help — but they can't see your Obsidian vault, your GitHub activity, or your Google Calendar. And sending all of that to a cloud LLM isn't an option for client work.

---

What it does

rebalance OS is a local-first work operating system that ingests your Obsidian vault, GitHub activity and artifacts, recent git history, and calendar into a queryable SQLite database — then lets any MCP-capable host or agent (ChatGPT, Gemini, Claude, Copilot, Cursor, Continue, and others where MCP is supported) answer questions about your own work, flag over-investment in specific projects, and move toward explicit weekly rebalance verdicts instead of vague retrieval.

---

Use cases

Morning briefing Ask "What's my day look like?" and get today's meetings, yesterday's commit activity, and a summary of relevant notes — in one shot, from your local machine.

Project balance check "Am I over-investing in client X?" surfaces commit velocity, PR activity, and note density per project. Flags when one repo is consuming >40% of your attention.

Knowledge retrieval "What did I decide about the Project Alpha embedding pipeline?" Semantic search across your vault and synced GitHub corpus, ranked by relevance and answered from the local SQLite evidence layer.

Handoff prep "Summarize everything I know about Project Y" pulls notes, recent commits, and open issues into a coherent brief — useful for client updates, team handoffs, or just getting back up to speed after a break.

Weekly rebalance "Where did my attention actually go this week, and what should change next week?" is the direction of travel: verdict-first summaries grounded in notes, calendar, git-pulse history, GitHub activity, and reminder signals.

Coming soon: reminder-driven follow-up Sleuth reminder ingestion is live as structured data and is intended to become another attention signal alongside calendar and git history.

---

High-level architecture

Data sources
  Google Calendar   ──┐
  GitHub activity   ──┤
  GitHub artifacts  ──┤
  Git pulse history ──┤──▶  scheduler / on-demand sync ──▶ SQLite + sqlite-vec
  Obsidian vault    ──┤      (launchd on macOS,           (vault chunks,
  Sleuth reminders  ──┤       Task Scheduler on            github_activity,
  Slack [planned]   ──┤       Windows, cron on Linux)      github_artifacts,
  Email [planned]   ──┘                                     calendar_events,
                                                              git-pulse reports,
                                                              semantic_documents)
                                     │
                                     ▼
                           MCP server (Python)
                           rebalance tools:
                             ask
                             query_notes
                             query_github_context
                             search_vault
                             github_balance
                             github_release_readiness
                             github_close_candidates
                             review_timesheet
                             classify_event
                             sleuth_sync_reminders
                             audit_modules
                                     │
             ┌───────────────────────┼────────────────────────┐
             ▼                       ▼                        ▼
      ChatGPT/Gemini           Claude/Copilot          Cursor/Continue
      (where MCP works)       (MCP clients)             (MCP clients)

The MCP server speaks standard JSON-RPC — no LLM-specific logic inside it. Any MCP-compatible client works without modification.

For layer roles, tool surface, server configuration, and host adapter setup (Claude Desktop, Cursor, VS Code, Continue), see MCP.md.

---

Why Markdown files and local LLMs make this possible

Obsidian stores everything as plain .md files. No proprietary database, no sync lock-in, no API needed — just a folder on your disk. That makes ingestion a simple recursive file scan: parse frontmatter, chunk by headings, extract tags and wikilinks, embed, and index. Recent work extends that same pattern beyond the vault: embeddable GitHub artifacts now flow into the same unified semantic document layer instead of living in a separate vector silo.

Local LLMs — such as Qwen3 via Ollama or LM Studio-compatible models — close the loop. Your vault content can stay local and be queried without sending note content to a hosted LLM by default. GitHub and Google Calendar data are pulled from their APIs, then cached and queried locally. The model runs on-device (optimized for Apple Silicon via MLX), retrieves context from the local vector store, and answers in seconds.

The result is an AI assistant that actually knows your work — because it's reading the same files and synced local history you are.

---

Tech stack

Layer	Tool
Notes	Obsidian (plain .md)
Local activity history	git-pulse sync repo + recap/report layer
Vector DB	SQLite + sqlite-vec
Embeddings	Qwen3-Embedding-0.6B via mlx-embeddings (Apple Silicon MLX)
LLM synthesis	Qwen3-0.6B via mlx-lm (on-device, Layer 1)
Calendar	Google Calendar API (direct client, OAuth2)
GitHub	GitHub REST API + PAT
Reminders	Sleuth Web API (structured sync)
MCP server	Python mcp SDK (FastMCP, stdio)
LLM clients	Any MCP host (Claude Code, Copilot, Cursor, Continue, Claude Desktop, and others)

---

Roadmap

• Architecture and design
• Project registry + MCP onboarding tools
• GitHub activity scanner + 30-day A/B/C band classification
• GitHub artifact sync + local semantic query (issues, PRs, comments, reviews, commits)
• Unified semantic index across vault and GitHub (semantic_documents, semantic_embeddings)
• GitHub readiness inference from local repo signals (milestones, linked PRs, branches, releases)
• GitHub issue <-> PR close-candidate reconciliation with high/medium-confidence recommendations
• Obsidian vault ingester (parse, chunk, keywords, links)
• Qwen3 embedding pipeline (sqlite-vec, semantic search)
• Google Calendar integration (OAuth2, 1-year retention)
• Git-pulse local repo discovery, recap layer, health checks, and sync hardening
• Sleuth reminder sync (structured ingest)
• ask tool — multi-source natural language query with local LLM synthesis
• Temporal context (day-of-week, work/off/vacation awareness)
• Daily scheduler scripts (launchd plist, install helper)
• Calendar daily/weekly reports with project aggregation and time totals
• Configurable hours format (decimal or h:m) for calendar reports
• Agent review layer for calendar events (review_timesheet, classify_event MCP tools)
• DRY calendar helpers (shared datetime parsing, duration calc, connection setup)
• CI test suite (GitHub Actions, Python 3.12/3.13)
• Weekly rebalance note generation with verdicts, evidence, and next moves per project
• Attention ledger contract (project_targets, attention_events, attention_feedback, rollups)
• Narrower verdict-first MCP surface (weekly_rebalance, project_attention, unattributed review)
• Gmail inbox integration (newest 100 inbox messages, semantic participation via subject + snippet)
• Slack integration beyond reminder/task signals
• Email → project auto-correlation (alias map + co-occurrence)

Getting Started

Prerequisites

• macOS with Apple Silicon (M1+)
• Python 3.13 recommended for the local MLX embeddings stack
• An Obsidian vault (local folder with .md files)
• A GitHub Personal Access Token with repo:read scope (create one here)
• Claude Code (CLI or VS Code extension)

Step 1 — Clone and install

git clone https://github.com/Hypercart-Dev-Tools/rebalance-OS.git
cd rebalance-OS
/opt/homebrew/bin/python3.13 -m venv .venv
.venv/bin/pip install -e ".[embeddings,calendar]"

Step 2 — Ingest your vault

# Parse all .md files, chunk by headings, extract keywords and links
.venv/bin/rebalance ingest notes --vault /path/to/your/vault --database rebalance.db

# Generate vault embeddings
.venv/bin/rebalance ingest embed --database rebalance.db

Step 3 — Connect GitHub

# Store your PAT
.venv/bin/rebalance config set-github-token <github-pat>

# Scan recent activity (commits, PRs, issues across all your repos)
.venv/bin/rebalance github-scan --token <github-pat> --database rebalance.db

# Sync detailed GitHub artifacts into the local SQLite corpus
.venv/bin/rebalance github-sync-artifacts \
  --repo owner/repo \
  --database rebalance.db

# Backfill the unified semantic layer from vault + GitHub
.venv/bin/rebalance semantic-backfill --source vault --source github --database rebalance.db

# Embed the unified semantic layer (downloads Qwen3-Embedding-0.6B on first run)
.venv/bin/rebalance semantic-embed --source vault --source github --database rebalance.db

# Query the unified semantic corpus without re-reading GitHub live
.venv/bin/rebalance semantic-query "What is close to deploy?" --source vault --source github --database rebalance.db

You can still use the source-specific commands:

.venv/bin/rebalance github-embed --database rebalance.db
.venv/bin/rebalance github-query "What changed in release readiness?" --database rebalance.db

Step 4 — Connect Google Calendar (optional)

OAuth Desktop app credentials are already bundled in the repo. You do not need to create a Google Cloud project or download a client_secret.json.

4a. Install with calendar support

.venv/bin/pip install -e ".[calendar]"

4b. Authorize this device

.venv/bin/python scripts/setup_calendar_oauth.py --test

A browser window opens — log in with your Google account and click Allow. The script prints your available calendars and their IDs. Your token is saved locally at ~/.config/gcalcli/oauth (never in the repo).

If you want MCP agents to create events, re-run auth with write access:

.venv/bin/python scripts/setup_calendar_oauth.py --write-access --test

Joining a team? If a teammate sent you a pre-filled calendar_config.json, place it at temp/calendar_config.json and skip to step 4d.

4c. Create your config

mkdir -p temp
cp calendar_config.example.json temp/calendar_config.json

Edit temp/calendar_config.json with your preferences:

Field	What to put here
calendar_id	Calendar ID from step 4b, or "primary" for your main calendar
exclude_titles	Exact event titles to hide from reports (e.g., "Lunch", "Check Slack")
aggregator_skip_words	Broad terms skipped in project grouping labels only (e.g., "wrap", "setup")
timezone	Your local timezone (e.g., "America/Los_Angeles")
hours_format	"decimal" (default, e.g. 4.50h) or "hm" (e.g. 4h 30m)

4d. Sync and run reports

# Pull events (use --days-back 365 for initial backfill)
.venv/bin/rebalance calendar-sync --days-back 30

# Generate reports
.venv/bin/rebalance calendar-daily-report
.venv/bin/rebalance calendar-weekly-report
.venv/bin/rebalance calendar-weekly-report --vault /path/to/vault --write-week-note

For the full guide — including team setup, Claude Code prompts, and project definitions — see GOOGLE_CALENDAR.md.

Step 5 — Connect Gmail (optional)

The Gmail ingest uses Google Application Default Credentials and stores message metadata plus Gmail-provided snippets only. It does not parse full message bodies in Phase 1.

5a. Enable the Gmail API once

gcloud services enable gmail.googleapis.com

5b. Authorize this device

gcloud auth application-default login --scopes=https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/cloud-platform

This stores the token at ~/.config/gcloud/application_default_credentials.json.

5c. Optional: narrow the inbox query

Add a gmail_query_filter key to temp/rbos.config. Example:

{
  "gmail_query_filter": "in:inbox -category:promotions -category:social"
}

If unset, rebalance defaults to in:inbox.

5d. Sync and verify

Call the MCP refresh entry point with scope=["email"], then confirm the email block appears in index_status() and email hits show up in semantic_query().

Step 6 — Start using with Claude Code

The .mcp.json at the project root auto-registers the MCP server. Open the project in Claude Code:

cd rebalance-OS
claude

Then ask:

"What should I focus on today?"
"Am I over-investing in any projects this week?"
"What meetings do I have tomorrow and what should I prep?"
"What did I decide about the embedding pipeline?"

Claude Code calls the ask tool behind the scenes — it gathers your project registry, GitHub activity, vault notes, and calendar events, synthesizes a first-pass answer via a local Qwen3 model, then Claude reviews and presents a refined answer.

Claude Desktop App

Manual config (recommended for now)

1. Open Claude → Settings → Developer → Edit Config to open ~/Library/Application Support/Claude/claude_desktop_config.json.

2. Add the rebalance server (use absolute paths):

   {
     "mcpServers": {
       "rebalance": {
         "command": "/absolute/path/to/rebalance-OS/.venv/bin/python",
         "args": ["-m", "rebalance.mcp_server"],
         "env": {
           "REBALANCE_DB": "/Users/<you>/Library/Application Support/rebalance-os/rebalance.db"
         }
       }
     }
   }

   REBALANCE_DB is optional as of 0.28.0 — src/rebalance/paths.py defaults to the canonical app-data path (~/Library/Application Support/rebalance-os/rebalance.db on macOS, $XDG_DATA_HOME/rebalance-os/rebalance.db on Linux). Set it explicitly only when you want to override that default. Stale env-var values silently fall through to the canonical path, so updating REBALANCE_DB here is never urgent. To move an existing DB into the canonical location, run python -m rebalance.paths --migrate (idempotent; also moves the -wal and -shm sidecars). Launchd jobs in scripts/com.rebalance-os.*.plist don't set REBALANCE_DB at all — they rely on the same resolver fallback, so no plist edits are needed when the canonical path moves or new sync jobs are added.

3. Quit and reopen Claude Desktop. The rebalance tools appear in the tool picker (hammer icon).

4. Ask "What should I work on today?" to verify.

For detailed setup, troubleshooting, and other MCP hosts, see MCP.md — Claude Desktop.

Extension (.mcpb) — coming soon

rebalance OS will also ship as a Claude Desktop Extension. The extension packaging step (mcpb pack) requires bundling all Python dependencies into the archive. This is not yet automated — use the manual config above for daily use. See manifest.json for the extension spec.

Other MCP hosts

The server works with any MCP-compatible client. Config files are provided for:

• Claude Code — .mcp.json (auto-loaded on cd rebalance-OS && claude)
• VS Code (Copilot/Continue) — .vscode/mcp.json (auto-loaded on workspace open)
• Claude Desktop — manual config (see above) or extension (.mcpb, coming soon)
• Cursor — see MCP.md for config snippet

Code Intelligence

ask-self is an external RAG-based code and docs scanner that builds a local queryable index for this repository without vendoring its code here.

This repo runs ask-self in portable mode with fully-local Qwen embeddings — the SQLite index is committed at ask_self/index/rebalance-OS.sqlite, so a fresh clone can query immediately with no ingest and no API keys.

Last ingested: see git log -1 --format=%ai -- ask_self/index/rebalance-OS.sqlite

Query this repo (no setup required)

./scripts/ask-self-query.sh "How does dashboard rendering work?"

The query wrapper pins --db-path to the committed portable DB, so it works on a fresh clone.

Refresh the index (maintainers only)

TOKENIZERS_PARALLELISM=false ./scripts/ask-self-ingest.sh --mode all --no-architecture-md --concurrency 1

Notes:

• --no-architecture-md is intentional: the curated ARCHITECTURE.md is hand-edited and should not be regenerated.
• --concurrency 1 and TOKENIZERS_PARALLELISM=false avoid a macOS fork+torch crash in sentence-transformers.
• Embedding is local (Qwen3-Embedding-0.6B via sentence-transformers) — no Gemini API key needed for ingest or query.
• Synthesis (the answer step) still defaults to Gemini unless you pass --retrieval-only or configure a local synthesis provider in ask_self/ask_self_harness.json.

The wrappers require ASK_SELF_PATH to point at your local ask-self checkout (no default — the scripts fail loudly if it isn't set):

export ASK_SELF_PATH="$HOME/Documents/GitHub/ask-self"

CLI reference

All tools are also available as CLI commands:

rebalance ask "What should I work on today?" --database rebalance.db
rebalance ask "What should I work on today?" --database rebalance.db --no-llm  # raw context only
rebalance query "embedding pipeline" --database rebalance.db                   # semantic search
rebalance search "project alpha" --database rebalance.db                       # keyword search
rebalance ingest notes --vault /path/to/vault --database rebalance.db          # re-ingest (delta)
rebalance ingest embed --database rebalance.db                                 # embed new chunks
rebalance github-scan --token <github-pat> --database rebalance.db             # refresh GitHub data
rebalance github-close-candidates --repo owner/name --database rebalance.db    # open issues likely fixed by merged PRs
rebalance calendar-sync --database rebalance.db                                # refresh calendar
rebalance calendar-daily-report                                                # today's events + project breakdown
rebalance calendar-weekly-report                                               # this week's summary + aggregator
rebalance calendar-weekly-report --vault /path/to/vault --write-week-note     # write week-of-YYYY-MM-DD.md and re-index it
rebalance calendar-daily-totals                                                # daily event count + duration stats

---

License

Copyright 2025-2026 Hypercart DBA Neochrome, Inc.

Licensed under the Apache License, Version 2.0.

You may use, reproduce, modify, and distribute this software and its documentation under the terms of the Apache 2.0 License. Attribution is required — any redistribution must retain the above copyright notice.

See APACHE-LICENSE-2.0.txt for the full license text, or visit https://www.apache.org/licenses/LICENSE-2.0.

---

Contributing

Not open to contributions yet — getting the core right first. Watch the repo and come back when the first milestone lands.

---

Built by Hypercart — tools for agencies and solopreneurs who build on WordPress.