Nexus — Personal & Work AI Assistant

Nexus is a local, skill-driven personal and work AI assistant for Pi, Claude Code, and OpenCode. It combines:

• TASKS.md as the shared task board
• CLAUDE.md as generated working memory (hot cache)
• memory/ as long-term structured memory
• an interactive Pi interface for tasks, memory, calendar, logs, and status

How It Works

• work-start bootstraps and generates CLAUDE.md + memory/ when missing.
• work-update keeps tasks and memory current through interactive sync, using memory query for decoding and memory ingest for durable updates.
• task-management defines how TASKS.md is structured and updated.
• memory-management defines what belongs in hot memory vs deep memory, plus the core ingest, query, and lint workflows.

Skills in This Repo

Workflow and memory

Skill	Purpose
work-start	First-run initializer: checks/creates TASKS.md and bootstraps memory (CLAUDE.md + memory/).
work-update	Main ongoing sync flow for tasks + memory gaps, stale task triage, and context enrichment. Uses memory query for lookup/decoding and memory ingest for durable filing.
daily-sync	Collects your 3 standup answers and posts them to the current team daily thread in Slack.
meeting-notes	Extracts decisions, action items, task candidates, and durable memory updates from pasted meeting notes, with confirmation before edits.
task-management	Task conventions for TASKS.md (active, waiting, someday, done) and task update behavior.
memory-management	Two-tier memory system: compact CLAUDE.md hot cache + detailed memory/ knowledge base, with explicit ingest, query, and lint workflows.
memory-backup	Syncs CLAUDE.md, TASKS.md, and memory/ with a separate private Git repository.
time-log	Builds today's mapped ZEP time-log plan from Google Calendar and enters it only after guarded preview and explicit approval.
decision-matrix	Multi-criteria decision analysis with weighted scoring — builds comparison tables from ruminate.io templates or manual input.
journal-sync	Pulls recent Notion Journal entries into monthly files, grouped by year.
portfolio-update	Fetches live prices for equities in memory/projects/investment_portfolio.md.

External source readers

Skill	Purpose
gmail	Reads and searches Gmail via gog.
google-calendar	Reads Google Calendar via gog.
google-drive	Reads and searches Google Drive folders and files via gog.
slack	Reads and sends Slack messages via .claude/skills/slack/slack-cli.js with @slack/web-api.
notion	Reads, searches, and updates Notion pages, data sources/databases, Markdown, files, and Workers via the official ntn CLI.
notebooklm	Manages NotebookLM notebooks, sources, chats, and generated artifacts via notebooklm-py.

Research and web

Skill	Purpose
ketch	Searches, scrapes, and crawls the web, public code, and curated documentation for cited research.
ddgr	Runs lightweight DuckDuckGo web and bang searches from the command line.

Pi Agent Extensions

This repository includes custom UI extensions for pi, the coding agent framework.

The Pi extension provides a continuous status bar widget and several interactive modals to manage your workflow directly within the TUI:

Command	Purpose
/tasks	Interactive TUI modal to view TASKS.md categories, page through tasks, and mark open tasks as done (uses Space or Enter).
/memory	Fuzzy file browser for the memory/ directory. Provides a scrollable file preview with markdown rendering (r to toggle raw source), fast keyboard navigation, and an action to load a selected file into the current session context.
/calendar	Overlay showing upcoming Google Calendar events via gog.
/logs	Interactive modal to page through memory/log.md entries (Older/Newer), keeping you aware of recent context changes.
/status	Shows the Nexus workspace, session, model, context usage, task count, latest memory log entry, and backup status.

Press Ctrl+Shift+T to open the tasks modal. When a task is marked done, the extension updates TASKS.md and runs the configured memory backup. Project extensions under .pi/extensions/ are loaded by Pi for this workspace; restart Pi or start a new session after changing extension code.

Project-local Pi Subagents

This repo also defines project-only subagents for the @tintinweb/pi-subagents extension. They live under .pi/agents/, so they apply only to this workspace and are not installed globally.

Agent	Purpose	Writes?
activity-scanner	General read-only scanner for Slack, Gmail, Calendar, Drive, Notion, TASKS.md, and memory context. Used by workflows such as work-update and optionally daily-sync to collect evidence without consuming the parent agent's context.	No
task-reconciler	Compares task candidates against TASKS.md and returns triage recommendations: already tracked, new candidate, stale, completion signal, waiting-on change, duplicate, or unclear.	No
memory-curator	Classifies candidate memory updates against CLAUDE.md and memory/, recommending safe existing-page updates, glossary/hot-cache candidates, new-page confirmations, or ignored transient noise.	No

Typical workflow: Run /scan in a dedicated Pi tab to schedule read-only activity scans at 9am, 12pm, 3pm, and 6pm on weekdays. After the final scan completes, the same tab starts the interactive work-update workflow using the day's findings. Scheduled scans only run while that session is active or resumed, missed runs are not replayed, and task or protected-memory changes still require confirmation.

If you add or rename agents, restart Pi or start a new session so the Agent tool schema and /agents menu refresh.

Repository Structure

.
├── .claude/
│   └── skills/
│       ├── work-start/
│       ├── work-update/
│       ├── daily-sync/
│       ├── meeting-notes/
│       ├── task-management/
│       ├── memory-management/
│       ├── decision-matrix/
│       ├── memory-backup/
│       ├── time-log/
│       ├── portfolio-update/
│       ├── journal-sync/
│       ├── ketch/
│       ├── ddgr/
│       ├── gmail/
│       ├── google-calendar/
│       ├── google-drive/
│       ├── slack/
│       ├── notion/
│       └── notebooklm/
├── .pi/
│   ├── agents/
│   │   ├── activity-scanner.md
│   │   ├── task-reconciler.md
│   │   └── memory-curator.md
│   ├── extensions/
│   ├── prompts/
│   │   └── scan.md
│   └── settings.json
├── TASKS.md         # generated/maintained by workflow
├── CLAUDE.md        # generated hot-memory file
├── package.json     # Node dependencies for local skill tooling
└── memory/
    ├── glossary.md
    ├── journals/
    │   ├── index.md
    │   └── YYYY/          ← monthly entries + yearly summary per folder
    ├── people/
    ├── projects/
    ├── context/
    └── topics/

Quick Start

1. Install the core dependencies:

   npm install
   uv sync

2. Open the repository in Pi, Claude Code, or OpenCode.
3. Run /work-start to initialize TASKS.md, CLAUDE.md, and memory/.
4. Use /work-update regularly to keep tasks and memory current.
5. Configure only the external integrations you need.

When using Pi:

• Use /tasks, /memory, /calendar, /logs, and /status for the interactive workspace interface.
• Optionally install @tintinweb/pi-subagents to enable the project-local agents in .pi/agents/.
• Optionally run /scan in a dedicated Pi tab for workday monitoring and an automatic interactive end-of-day update.

Other optional workflows:

• Use /daily-sync to post your standup update to the correct Slack thread.
• Configure MEMORY_BACKUP_DIR to use /memory-backup.
• Configure Notion and run /journal-sync to import recent Journal entries into memory.

Prerequisites

• Pi, Claude Code, or OpenCode
• Node.js and npm
• Python 3.12 or later
• uv
• Core dependencies:
  • npm install
  • uv sync
• gog CLI:
  • brew install gogcli
• ntn CLI for Notion:
  • npm install --global ntn
  • or use the local helper: npm run --silent ntn -- ...
• Chromium for NotebookLM browser authentication:
  • uv run playwright install chromium

The external-service CLIs and Chromium installation are needed only for the integrations that use them.

Environment variables

Create a .env file in the repository root for the integrations you use:

Variable	Used by
SLACK_TOKEN	Slack
NOTION_API_TOKEN	Notion
NOTION_WORKSPACE_ID	Optional Notion workspace targeting
GOG_ACCOUNT	Optional default Google account
MEMORY_BACKUP_DIR	Memory backup

Do not commit .env.

Authentication Setup

Google (Gmail + Calendar + Drive via gog)

1. Open Google Cloud Console.
2. Create/select a project.
3. Enable these APIs:
   • Gmail API
   • Google Calendar API
   • Google Drive API
4. Configure OAuth consent screen.
5. Create OAuth Client credentials (Desktop App recommended).
6. Download OAuth client JSON (example: ~/Downloads/client_secret.json).
7. Configure gog:
   • gog auth credentials ~/Downloads/client_secret.json
8. Authorize account:
   • gog auth add you@gmail.com
9. Set default account (optional):
   • gog auth manage
   • or export GOG_ACCOUNT=you@gmail.com

Slack (User token with required scopes)

1. Open Slack API Apps, then create/select your app.
2. In OAuth & Permissions, add User Token Scopes:
   • channels:history, groups:history, im:history, mpim:history
   • channels:read, groups:read, users:read
   • chat:write
3. Install/Reinstall app to workspace.
4. Copy User OAuth token (xoxp-...).
5. Create .env file and save your token in it:
   • SLACK_TOKEN=xoxp-your-token
6. Verify:
   • node .claude/skills/slack/slack-cli.js test

Notion (via ntn)

1. Create a Notion integration and copy its internal integration token.
2. Share each target page/database with the integration (... → Connect to).
3. Add the token to .env:
   • NOTION_API_TOKEN=ntn_your_token_here
   • optional: NOTION_WORKSPACE_ID=<workspace_id>
4. Verify:
   • npm run --silent ntn -- api v1/users

Use /notion for general Notion operations. Use /journal-sync to import the configured Journal data source into memory/journals/YYYY/month_YYYY-MM_text.txt. The sync state lives in memory/journals/index.md.

NotebookLM (via notebooklm-py)

1. Install the locked Python dependencies and Chromium:
   • uv sync
   • uv run playwright install chromium
2. Authenticate with Google:
   • uv run notebooklm login
3. Verify the setup:
   • uv run notebooklm status
   • uv run notebooklm list --json
4. If auth expires or verification fails:
   • uv run notebooklm auth check
   • uv run notebooklm login

For parallel workflows, prefer explicit notebook IDs (-n <id> or --notebook <id>) instead of relying on notebooklm use.

Memory backup

1. Clone your private backup repository somewhere outside this workspace.
2. Ensure the clone already exists, is a Git repo, and has push access configured.
3. Add MEMORY_BACKUP_DIR to your workspace .env file:
   • MEMORY_BACKUP_DIR=/your/path/to/private-backup-repo
4. Run the skill:
   • /memory-backup - push local memory to the backup repo
   • /memory-backup --pull - pull latest backup into this workspace
   • /memory-backup --sync - pull latest, then push local memory
   • /memory-backup --dry-run - preview push

MEMORY_BACKUP_DIR must point to a clean local clone of a separate private Git repo.

For two-computer use, run /memory-backup --pull or /memory-backup --sync when starting work, and /memory-backup after memory/task changes. Pull/sync refuse to overwrite local changes in CLAUDE.md, TASKS.md, or memory/.

Privacy and local data

• memory/, TASKS.md, CLAUDE.md, and .env contain local or potentially sensitive information and are intentionally excluded from Git.
• Never commit OAuth credentials, API tokens, cookies, or browser authentication state.
• Use a private repository for memory backups.
• External-reader skills can send selected email, calendar, Slack, Notion, or Drive content to the active AI provider as working context. Review your provider and workspace policies before using them with sensitive data.
• Review .claude/settings.json and the project-local Pi configuration before enabling integrations or granting additional permissions.

Operating Notes

• work-update is intentionally interactive: it asks before creating/updating tasks and memory entries.
• CLAUDE.md should remain compact; detailed context lives in memory/.
• If key files are missing, run /work-start to repair/bootstrap the system.