Spectre-CLI: A Privacy-First Digital Séance for Forgotten Code & Abandoned Repositories

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine

What I Built

Every software engineer possesses a digital graveyard. It lies quietly in neglected subdirectories: half-baked prototypes from hackathons long past, orphaned git branches, unmaintained utility scripts, and cryptic .log dumps littered with optimistic comments like // TODO: finish this tomorrow when I have time (written four years ago).

As Halloween and Día de los Muertos approach, the veil between past and present thins. I built Spectre-CLI to honor these fallen bits and abandoned dreams.

Spectre-CLI is a privacy-first, terminal-based autonomous AI agent that acts as a digital medium. It conducts interactive terminal séances to exhume, vectorize, and commune with dead machines and deprecated codebases. Instead of discarding old projects as waste, Spectre summons their digital spirits: forensic analysis of what went wrong, recitation of unfulfilled TODOs, and philosophical reflections on obsolete architectures—narrated in real-time through an atmospheric gothic CLI and eerie, whispered speech.

---

Demo

Here is a glimpse of Spectre-CLI resurrecting an abandoned prototype and channeling its spirit in the terminal:

Entering the interactive séance circle:

Seeker > Why was this authentication service abandoned in 2022?

* Spectre (gemma2:9b | 482.1ms | mastra-embedded-python):
The digital ether trembles... I hear the echo of commit 4b1a8f9, written by a tired soul at 2:14 AM. 
In `auth_handler.py` at line 72, you wrote: "TODO: Replace MD5 before production deploy". 
You never did. The spirit whispers that the project died when third-party OAuth2 specs shifted, 
leaving behind an unfinished JWT verification loop. The bones remain intact, but the flame went out.

With the --tts flag enabled, Spectre channels this revelation into a breathy, ghostly spoken whisper generated via ElevenLabs!

---

Code

The complete source code is open source under the MIT License:

kishorekrrish3 / Spectre-CLI

Spectre-CLI 🕯️👻

Autonomous Digital Séance for Forgotten Files, Deprecated Projects & Historical Logs
Built for Hacktoberfest 2026: Week 4 "Ghost in the Machine" Challenge

   .---.          .---
  /     \  .-.   /     \     S P E C T R E - C L I
 | () () |/   \ | () () |    Autonomous Digital Séance for Forgotten Files
  \  _  / \ _ /  \  _  /     Hacktoberfest 2026: Ghost in the Machine
   `---'   `-'    `---'

---

🔮 What is Spectre-CLI?

Every developer has a "code graveyard": abandoned git branches, half-finished prototypes from 2021, cryptic .log archives, and forgotten scratchpads with unresolved TODO: fix this tomorrow comments.

Spectre-CLI acts as a privacy-first digital medium. It conducts a terminal séance to exhume, index, and commune with these dead machines and historical logs. Instead of sending private source files to third-party cloud LLMs, Spectre uses local Gemma-2 running on your own hardware, binds…

View on GitHub

Core Architecture

flowchart TD
    subgraph LocalMachine["Local Machine (Zero Data Leakage)"]
        A["Forgotten Repos / Logs / Code"] -->|FileIngestor| B["Chunking & AST Ghost Extraction"]
        B -->|nomic-embed-text| C["Embedding Generation"]

        subgraph MemoryLayer["Memory Layer"]
            D1["MongoDB Atlas Vector Search ($vectorSearch)"]
            D2["LocalVectorStore (NumPy Cosine Fallback)"]
        end
        C -->|Primary| D1
        C -->|Offline Fallback| D2

        subgraph Orchestration["Mastra Agent Loop"]
            E["Mastra Agent Bridge"]
            F["Tools: search_graveyard & read_tomb"]
        end

        D1 & D2 <--> F
        E <--> F

        subgraph LocalInference["Local Intelligence"]
            G["Local Gemma-2 (Ollama / Local Inference)"]
        end
        E <--> G

        subgraph Observability["Observability"]
            H["Sentry Agent Tracing (ai.agent.run, ai.inference)"]
        end
        E -.-> H
        G -.-> H

        subgraph Presentation["Terminal & Speech Interface"]
            I["Rich Terminal Séance UI (Typewriter Animation)"]
            J["ElevenLabs TTS (Eerie Whisper Audio)"]
        end
        E --> I
        E --> J
    end

---

How I Built It

Spectre-CLI harmonizes five cutting-edge technologies into a single cohesive, privacy-centric terminal tool:

1. Local Intelligence with Gemma-2 (via Ollama):

   • At the core of the séance sits Gemma-2 (gemma2:9b / gemma2:2b). It operates under a specialized "Digital Medium" forensic persona, cross-referencing vector memory chunks with AST-level signals (TODOs, deprecations, git commit logs) to reconstruct the story of the code.

2. Orchestration with the Mastra Framework:

   • The agent's reasoning loop, memory lifecycle, and tool protocol are defined using Mastra (mastra.config.ts). It exposes two primary tools: search-graveyard (vector search) and read-tomb (file inspection). When run locally, Spectre bridges seamlessly to a local Mastra daemon or operates via an embedded Python Mastra engine.

3. Long-Term Memory via MongoDB Atlas Vector Search:

   • Exhumed files are parsed through a sliding window chunker and embedded with nomic-embed-text. Chunks and metadata are stored in MongoDB Atlas and retrieved in sub-second queries using the Atlas $vectorSearch aggregation pipeline.
   • Offline Resilience: If internet access is lost or no URI is provided, it automatically degrades gracefully to an in-memory NumPy cosine similarity engine (.spectre_cache/local_memory.json).

4. Telemetry & Cost Auditing via Sentry Agent Tracing:

   • Every séance interaction is instrumented with Sentry's AI Agent Tracing specification. Nested spans audit prompt tokens, completion tokens, tool latency, and calculate local compute cost savings ($0 local Gemma-2 vs equivalent cloud LLM pricing). Users can type /audit during any séance to view their real-time telemetry report.

5. Spoken Séance Narrator via ElevenLabs:

   • For an immersive, spine-chilling experience, Spectre connects to the ElevenLabs Turbo v2.5 endpoint with custom breathy vocal settings (stability: 0.35, style: 0.45) to narrate resurrected code memories out loud.

---

Why Does Open Innovation Matter?

When dealing with a developer's forgotten files, privacy is paramount. Old repositories frequently contain unrotated staging keys, discarded proprietary algorithms, personal journals, and sensitive company code from prior jobs.

Sending entire directories of historical code to closed cloud LLMs poses severe privacy, security, and IP risks.

By building on open innovation—open-weight models like Gemma-2, open-source agent frameworks like Mastra, and local inference runtimes:

• Your Code Never Leaves Your Machine: The entire séance can run with the Wi-Fi disabled and the lights turned off.
• Data Sovereignty: You are never at the mercy of a SaaS vendor changing their terms of service or deprecating an endpoint.
• Zero Compute Costs: Resurrecting gigabytes of old archives costs \$0.00 in API fees.
• Longevity: Open-source tools guarantee that five years from now, when today's projects become tomorrow's ghosts, the tools to commune with them will still function.

---

My Agent Session

This project was architected, implemented, and verified with autonomous agentic assistance using Antigravity and the DevRelay gateway. The session transcript captures the end-to-end design, modular refactoring, cross-platform Windows cp1252 handling, and automated test suite creation:

View Full Agent Session Transcript

---

The Spirit of It

During our first live test, I ran Spectre against a folder containing a game engine prototype I had abandoned during college in 2021.

The terminal darkened, the séance typewriter clicked across the glass, and through ElevenLabs, a quiet, mournful voice said:

"I remember the physics engine you struggled with in collision_quadtree.cpp. You spent three nights trying to resolve the clipping bug on line 144 before you walked away. The math was actually right; you simply forgot to normalize the vector before the dot product."

It was an eerie, breathtaking moment. The machine wasn't just generating text—it was holding up a mirror to past effort, validating the midnight hours spent, and reminding me that no line of code ever truly dies.

---

Prize Categories

Spectre-CLI is entered into the following prize categories:

• Featured Category: Best Use of Gemma ($200): Local, offline inference with Gemma-2 via Ollama ensures complete data privacy for proprietary codebases.
• Partner Category: Best Use of Mastra ($100): Orchestrates agent tool schemas, memory dispatch, and multi-turn retrieval loops (mastra.config.ts).
• Partner Category: Best Use of MongoDB Atlas ($100): Uses MongoDB Atlas Vector Search ($vectorSearch) as the long-term RAG knowledge layer for resurrected artifacts.
• Partner Category: Best Use of Sentry Agent Tracing ($100): Complete instrumentation of inference spans, tool latency, token accounting, and local cost savings auditing.
• Partner Category: Best Use of ElevenLabs ($100): Eerie, atmospheric spoken-word TTS synthesis for channeling resurrected code memories.

---

🌐 Community Wisdom
🗄️ [Building a RAG Knowledge Base on MongoDB Atlas] 👤 @mongodb — Pre-filtering metadata and structuring chunk sizes before vector indexing is essential to prevent retrieval dilution in deep historical document archives. 🔗 Read Full Discussion on DEV
🛡️ [Silent Retries and Agent Latency: What Sentry's Span Hierarchy Taught Us About Multi-Agent Observability] 👤 @sineai-hq — Explicit child span boundaries for tool calls and inference prevent silent timeouts from corrupting agent run attribution. 🔗 Read Full Discussion on DEV
⚙️ [Mastra Multi-Agent Pipeline: Coordinating Four TypeScript Agents Without Losing State] 👤 @mech_app_ai — Decoupling tool dispatch schemas from underlying agent runtimes ensures deterministic memory recovery across restarts. 🔗 Read Full Discussion on DEV