BeeNote

From realization to repo

Comment

Inspiration

Whenever I get exhausted while building my project and go for a walk, a lot of unique ideas come to mind—but by the time I return to my desk, half of them are gone. I thought there must be a tool that can listen to my thoughts and log them directly into my repo.

However, wearable voice devices often mishear coding terms, transcribing them into something completely different from what I meant (e.g., turning handle_token_expiry into separate, garbled plain words). Generic voice note apps don't understand code syntax or project structure, leaving developers with messy notes that take more time to decipher than they save.

What it does

BeeNote is a code-aware voice memo capture tool that has direct knowledge of your local repository.

  1. Scans & Indexes: BeeNote inspects your local repository and maps out all existing files, classes, and functions with their exact line numbers.
  2. Context-Aware Correction: When you speak an idea on the go, BeeNote compares the speech transcript against your codebase index and corrects misheard technical terms to the exact code identifiers you meant.
  3. 3-Column Review & Send: It presents your note in a dark, high-contrast review view:
    • Column 1 (What Bee Heard): Raw spoken transcript.
    • Column 2 (Codebase Match): Green diff-style badges linking to real code symbols (file:line), and neutral tags for new entities.
    • Column 3 (Action Plan): Clean markdown summary that you can edit inline or reject false matches from with one click.
  4. Drops into Editor: Clicking "Drop into Editor" atomically prepends the timestamped markdown note straight to the top of BEE_NOTES.md in your project root.

How we built it

We kept the architecture lightweight, offline-first, and reliant on standard libraries rather than heavy cloud infrastructure:

  • Backend: Built with Python 3.10+, FastAPI, and Uvicorn for fast asynchronous request handling.
  • AST Codebase Scanner (scanner.py): Uses Python's built-in ast module to statically parse Python files into Abstract Syntax Trees, extracting function names (ast.FunctionDef) and class names (ast.ClassDef) along with their exact lineno. It uses os.walk to traverse the repository, pruning ignored folders (.git, node_modules, venv) in-place.
  • Fuzzy Phonetic Matcher (matcher.py): Normalizes snake_case and camelCase identifiers into plain space-separated tokens. It processes spoken words using an $n$-gram sliding window ($n \in {4, 3, 2, 1}$) and computes similarity against indexed symbols using Python's difflib.SequenceMatcher: $$\text{Similarity}(S_1, S_2) = \frac{2 \cdot M}{|S_1| + |S_2|}$$ where $M$ is the number of matching characters and $|S_1|, |S_2|$ are the lengths of the respective strings. Candidate phrases with a similarity score $S \ge 0.80$ are linked to their source file and line.
  • Atomic Note Writer (writer.py): Formats approved notes and prepends them using a Last-In, First-Out (LIFO) pattern to BEE_NOTES.md.
  • Frontend: Single-page interface built from scratch in vanilla HTML5, CSS3 Grid, and native JavaScript (ES6+)—no React, no npm, and no build pipeline to slow startup down.

Challenges we ran into

  • Bridging Spoken English and Code Syntax: Speech recognition splits programming identifiers like user_auth_controller.py into separate English words ("user auth controller py"). Direct string lookups failed completely until we built a normalization pipeline in matcher.py that strips punctuation, decomposes camelCase, and maps multi-word sequences into single tokens before computing similarity.
  • Preventing False Positives on Novel Ideas: Early on, forcing every technical noun to match an existing file created bad links when talking about unwritten features. We solved this by enforcing a strict similarity threshold ($S \ge 0.80$) and tagging unmatched terms neutrally as a new entity rather than throwing an error, alongside a one-click "Reject match" button in the UI.
  • Hardware-Decoupled Testing: Without a physical Bee wearable device on hand during development, we couldn't rely solely on live Bluetooth/hardware triggers. We designed an open HTTP transcript ingestion endpoint (POST /api/transcripts/ingest) with a built-in UI simulator, allowing us to test our entire AST parsing, matching, and file-writing pipeline with complete reproducibility.

Accomplishments that we're proud of

  • Sub-Millisecond Offline Matching: Instead of relying on a slow Language Server Protocol (LSP) daemon or paying for external vector databases, our in-memory AST symbol table resolves code terms with query latency $\tau < 5\text{ ms}$ completely offline.
  • Developer-Centric UI: Crafted a high-contrast dark interface inspired by Linear, Raycast, and GitHub PR diffs that provides instant visual clarity without any bloated UI component libraries.
  • Closing the Loop: Delivering a full end-to-end workflow where a messy spoken thought can be reviewed, refined, and written directly into the developer's project files in three clicks.

What we learned

  • Python's Standard Library is Immensely Capable: Python's built-in ast and difflib modules provide enterprise-grade static analysis and string pattern matching out of the box without installing heavy compilers or third-party packages.
  • Human-in-the-Loop Architecture: Speech models will always mishear niche jargon. Providing a transparent 3-column diff view where users can visually audit matches, reject false positives, and edit text inline makes developer tools dependable rather than frustrating.
  • The Adapter Pattern for Hardware: Decoupling ingestion from processing through an HTTP ingestion contract means BeeNote works with local simulator triggers today, a browser microphone tomorrow, and a physical Bee wearable down the line without changing a single line of core matching logic.

What's next for BeeNote

  • Native VS Code Extension: Allowing "Drop into Editor" to highlight the referenced file and line directly inside an open VS Code editor tab.
  • Git Branch Context: Automatically tagging captured voice memos with the active Git branch and commit hash.
  • Multi-Project Workspace Switching: Enabling seamless switching between different local project directories with persistent session history.

Built With

Share this project:

Updates

Submission history