💡 Contextual Workspace Intelligence: Proactive Project Understanding on Launch

[github-actions[bot]]

Summary

When a workspace is selected, the avatar automatically and asynchronously analyzes the project structure, README, key configuration files, git history, and open issues to build contextual understanding BEFORE the first conversation begins. The avatar greets users with genuine project awareness — "I see your React project has a migration in progress and 3 open PRs. Want to pick up where you left off?" — instead of requiring users to re-explain their project context every session.

Market Signal

Cursor, Copilot, and Windsurf all index codebases for context-aware assistance, but they target developers in IDEs. No product does proactive project understanding for non-technical users in a conversational interface. The desktop-first agentic shift (Gartner, May 2026) shows that system-level integration — including file system awareness — is the baseline expectation for 2026 desktop AI agents.

User Signal

User Journey 2 (Marcus) explicitly describes the avatar examining the codebase and auth configuration. FR52-53 workspace selection provides the entry point but does not specify proactive analysis. Users consistently report that "starting from scratch every session" is frustrating. Cross-session memory (FR46-47) addresses conversation history but not project state awareness.

Technical Opportunity

The Claude Agent SDK's built-in file tools (Read, Glob, Grep) can scan workspace files during a lightweight initialization pass. Results are cached in SQLite (main/storage/memory.ts) and updated incrementally on subsequent launches. The analysis runs asynchronously after the avatar is ready (preserving NFR4 ≤3s cold launch). The workspace context feeds into the session prompt for claude-sdk-backend.ts, enriching every subsequent agent interaction.

Assessment

Dimension	Score	Rationale
Feasibility	high	Uses existing SDK file tools and SQLite caching. No new external dependencies. Lightweight analysis (README, package.json, git log) completes in seconds.
Impact	high	Transforms the avatar from a blank-slate assistant to a colleague who did their homework. Directly addresses "starting from scratch" frustration.
Urgency	med	Foundational capability that enhances every other feature. No external dependency window to catch, but high architectural leverage.

Adversarial Review

Strongest objection: Large repositories could take minutes to analyze, and the analysis results may be stale by the time the user starts working. Also, scanning user files proactively raises privacy expectations.

Rebuttal: Analysis starts with lightweight signals (README, package.json, .git/HEAD, recent git log) — completes in seconds. Full codebase analysis is progressive and optional. Results are cached and diff-updated on subsequent launches. Privacy is addressed by the existing workspace consent model (FR52) — the user explicitly chose to share this directory. The avatar only surfaces high-level project awareness, not file contents.

Suggested Next Step

Define the "lightweight project profile" schema — what signals to extract (README, package.json, git status, issue count). Implement as an async post-launch task in main process. Design avatar greeting templates that incorporate project awareness.