Veldrine Evelia Kaharwa

Posted on Oct 30 Originally published at github.com

🕯️ SpookyCode: The Haunted Autonomous AI Coding Agent That Possesses Your Codebase and Banishes Tech Debt

#devchallenge #hf26challenge

Hacktoberfest Open-Source AI Challenge: Ghost in the Machine Submission 👻🌼

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

What I Built

Most coding agents today are sterile, transactional autocomplete machines. And most developer tools treat code modification and deletion as a callous, unceremonious act: a cold rm -rf, a reckless automated edit, or a silent graveyard of broken branches.

I built SpookyCode 🩸🕯️💀 — an open-source autonomous AI coding agent that possesses your codebase, haunts your Git history, mocks your mistakes, and repairs your bugs—with every change isolated, validated, reviewable, and recoverable.

"SpookyCode is an open-source AI coding agent that possesses your codebase, haunts your Git history, mocks your mistakes, and fixes your bugs—with every change reviewable and recoverable."

SpookyCode takes the "Ghost in the Machine" theme literally: code isn't just disposable syntax; it possesses a mortal life. The CLI is its interface; the agent is the product.

The Autonomous Coding Agent Architecture:

SpookyCode operates an autonomous, multi-step engineering loop in an isolated workspace (Git worktree or sandbox clone) backed by deterministic tools and safety invariants:

Summon (spookycode possess "<task>"): The developer summons the entity with a natural language coding mission or bug fix.
Investigate: The agent crawls the codebase using search_codebase and read_code_file, discovering living syntax, classes, and call-sites without assumptions.
Plan: The agent formulates a surgical, multi-step execution plan before altering a single line.
Possess (Isolated Edits): The agent performs surgical modifications in an isolated workspace using edit_code_file and create_code_file. The developer's earthly working tree remains 100% untouched until approval.
Validate (Test & Recovery Loop): The agent autonomously runs the project test suite (run_project_tests). If tests fail, it reads the failure tracebacks, diagnoses the anomaly, and iterates until the curse is lifted and all tests pass.
Review: The agent evaluates inspect_diff and diagnose_syntax to verify cleanliness, minimal surface area, and syntax purity.
Present & Approve/Reject: SpookyCode displays a bloody Halloween review screen featuring a syntax-highlighted unified diff, test verdicts, and its eerie Spooky Verdict. The developer chooses to accept the possession (safely applying the patch to main) or dispel it with zero trace left behind.

The Supernatural Toolkit:

The Crypt First (make_crypt & verify_crypt): Before banishing any mortal file, SpookyCode vaults the code into a byte-for-byte SHA-256 vault in .crypt/<session>/vault/, verifying every hash mathematically.
The Requiem & Ofrenda (eulogize): Powered by Google Gemma and Pydantic AI, SpookyCode inspects AST symbols, line count, and function signatures, composing a poetic Victorian eulogy and inscribing an ofrenda tombstone.
The Eternal Graveyard (MongoDB Atlas): Every epitaph, eulogy, burial timestamp, and soul signature is permanently indexed in MongoDB Atlas (with local JSON fallback).
The Interactive Séance (spookycode seance): Mortals can summon the lingering ghost of any deceased file. Gemma channels the ghost, grounded directly in the vaulted source code, answering questions about legacy algorithms.
The Revenant's Bloody Roast (spookycode roast): Eerily critiques your pull requests and git diffs accompanied by ElevenLabs spectral cackles and sharp Victorian wit.
Haunted Commit History (spookycode haunt-history): Rewrites recent commits into gothic diary entries authored by computing pioneers (Ada Lovelace, Alan Turing, Grace Hopper) with 1-click restore.
Byte-for-Byte Resurrection (resurrect): Regret your sins? SpookyCode validates the crypt and resurrects the banished code with 100% byte-for-byte SHA-256 fidelity.
The Haunted Machine Sound Engine (audio.py): Cyber-horror voice synthesis via ElevenLabs and procedural synthetic glitch PCM wave synthesis.
Distributed Agent Tracing: Full Sentry GenAI tracing across agent reasoning spans and deterministic tool breadcrumbs.

Demo

Experience the full automated banishment, séance, and resurrection ritual:

git clone https://github.com/Tech-Vexy/spookycode.git
cd spookycode
uv sync
uv run spookycode demo

Terminal Ritual Walkthrough

   ______                   __          ______           __   
  / ____/____  ____  ____  / /____  __ / ____/____  ____/ /__ 
 /___ \ / __ \/ __ \/ __ \/ //_/ / / // /    / __ \/ __  / _ \
____/ // /_/ / /_/ / /_/ / ,< / /_/ // /___ / /_/ / /_/ /  __/
/_____// .___/\____/\____/_/|_|\__, / \____/ \____/\__,_/\___/ 
      /_/                     /____/                          
    🕯️ The Haunted Undertaker of Codebases 💀

Step 1: Manifesting mortal repository at 'demo_cemetery'...
  • Created mortal file: mortal_auth.py (a90bb6f154fb...)
  • Created mortal file: legacy_billing.py (fe41971d4a47...)
  • Created mortal file: phantom_worker.py (fe0ea8c93d04...)

Step 2: Commencing safe banishment ritual...
🌌 Sealing files in the sacred Crypt...
👻 Purged 3 files into Crypt crypt_20261027_230902...
✓ Code banished safely! Memorial tombstone inscribed at:
  demo_cemetery/TOMBSTONE.md

Step 3: Querying the Graveyard during a Séance...
╭─────────────────── 👻 Spirit Channeled: legacy_billing.py ───────────────────╮
│ Mortal Path: legacy_billing.py                                               │
│ Buried In Crypt: crypt_20261027_230902                                       │
│                                                                              │
│ "Bearer of calculate_vat, apply_rebate; rested across 24 mortal lines."      │
│                                                                              │
│ Here lies legacy_billing.py. In its mortal life it faithfully defined        │
│ calculate_vat and apply_rebate, bearing the weight of floating-point rules   │
│ through four long quarters without complaint. The veil opens, and its logic  │
│ sleeps peacefully under marigolds in the sacred Crypt.                       │
╰──────────────────────────────────────────────────────────────────────────────╯

Step 4: Regret your sins? Resurrecting code byte-for-byte...
✨ Resurrecting all souls from Crypt 'crypt_20261027_230902'...
✨ Resurrection Complete! Restored 3 files.
  • mortal_auth.py: MATCH (a90bb6f154fb...)
  • legacy_billing.py: MATCH (fe41971d4a47...)
  • phantom_worker.py: MATCH (fe0ea8c93d04...)
🎉 BYTE-FOR-BYTE FIDELITY CONFIRMED!

Interactive Commands

Interactive Séance: uv run spookycode seance "billing" (Chat directly with your dead code's ghost)
Eerie PR Roast: uv run spookycode roast --staged (Critiques changes with an ElevenLabs spectral laugh)
Haunt Git History: uv run spookycode haunt-history (Reversibly rewrite git log into gothic diary entries)
Tally Mortal Sins: uv run spookycode sins . (Scans for swallowed exceptions, naked tokens, and broken promises)

Code

The complete source code is open-source under the MIT License on GitHub:
👉 https://github.com/Tech-Vexy/spookycode

Architecture Overview

src/spookycode/
├── possess.py     # Autonomous Coding Agent: Worktree isolation, test iteration, diff review
├── agent.py       # Pydantic AI agent with Gemma, EulogyRecord & tool harnesses
├── crypt.py       # Crypt vaulting, byte-for-byte SHA-256 verification & resurrection
├── graveyard.py   # MongoDB Atlas upsert graveyard storage and regex-escaped search
├── workflow.py    # Temporal durable banish workflow, plain def activities & per-file retries
├── worker.py      # Dedicated Temporal worker daemon
├── seance.py      # Interactive séance channeling dead code with vaulted source memory
├── roast.py       # Eerie PR & code diff roaster with ElevenLabs spectral laugh
├── haunt.py       # Reversible haunted commit history with Lovelace, Turing, Hopper
├── tracing.py     # Sentry GenAI & agent distributed tracing, tool breadcrumbs & spans
├── horror.py      # Mortal sin scanner (redacted on-screen) & ASCII terminal calaveras
├── animation.py   # Rich live terminal ASCII candle, ghost, and dripping blood animations
├── audio.py       # Haunted Machine ElevenLabs TTS & sound synthesis engine
└── cli.py         # Complete CLI entrypoint with safety wards refusing / and $HOME

How I Built It

SpookyCode was engineered around modern open-source AI, agentic architectures, and durable systems:

1. The Autonomous Coding Agent: Pydantic AI & Isolated Workspaces

We designed SpookyCode with a single, highly capable agent backed by a controlled set of deterministic tools (possess.py). The agent decides what happens next; the tools enforce permissions and sandboxing:

Isolated Workspace (PossessionWorkspace): Operates inside a Git worktree (git worktree add -b spooky/possession-<id>) or sandbox clone. Edits are physically isolated from the developer's working tree until explicitly approved.
Code Tools: read_code_file (with line numbering and range slices), search_codebase (pattern matching across living files), edit_code_file (drop-in substring replacement), create_code_file.
Execution & Test Tools: run_project_tests (executes pytest in the workspace environment, capturing failure tracebacks), diagnose_syntax (AST parsing to catch syntax anomalies before running tests).
Git & Archaeology Tools: inspect_diff (real-time unified diff of workspace changes), inspect_git_history.
Haunting & Recovery Tools: banish_rotten_file (archives rotten code to .crypt before replacement), consult_crypt_ancestors (queries MongoDB ofrendas for dead code patterns).

2. The Intelligence: Google Gemma Across Configured Providers

Google Gemma powers the autonomous coding agent and the undertaker persona. SpookyCode builds a configurable provider chain, preferring Google Cloud Serverless Inference by default, with OpenRouter and Nvidia NIM available as provider choices and fallbacks. Gemma reads repository context, plans and edits code through the agent's tools, writes structured eulogies, grounds séances in archived source, critiques diffs, and generates optional prophecies and commit entries. Its output is constrained by deterministic tools and isolated workspaces, so the model proposes actions while the harness controls where edits and tests run.

3. Sentry GenAI & Distributed Agent Tracing

Every autonomous possession run, tool execution, and PR roast is traced via Sentry SDK. Tool executions generate structured breadcrumbs (gen_ai.tool), and multi-step agent actions are traced under gen_ai.agent spans with inputs, outputs, and model parameters.

4. Workflow Durability: Temporal

Banishment must never result in lost code. We implemented Temporal (temporalio) to execute a five-stage durable workflow (BanishWorkflow):

temporal_make_crypt: Synchronous activity archiving source code into .crypt.
temporal_verify_crypt: Verifies SHA-256 hashes against original files.
temporal_eulogize_file: Granular one-activity-per-file eulogy generation with exponential retry policies.
temporal_store_ofrendas: Idempotent upserts to MongoDB Atlas and local disk.
temporal_banish_files: Purges files only after crypt integrity is 100% verified. A dedicated worker (worker.py) listens on the spookycode-tasks task queue.

5. Graveyard Storage: MongoDB Atlas

While files disappear from disk, their spiritual essence remains. Every OfrendaDocument is preserved on MongoDB Atlas with unique index constraints and upsert semantics (update_one(..., upsert=True)). If offline, SpookyCode seamlessly falls back to local JSON crypt rolls.

6. Atmospheric Sensory Chills: ElevenLabs & Rich

ElevenLabs Haunted Machine Sound Engine (audio.py): Cyber-horror voice synthesis (The Awakening startup, The Eerie Laugh) voiced by the demonic voice (QsCWi7YXDSt3b03KRD8a), procedural sound effects (The Digital Haunting, Code Banishment suction, Resurrection particles) cached in assets/cache/ for instant, non-blocking playback, with graceful fallback to available account voices and procedural synthetic glitch waves.
Rich Halloween Blood Interface: Dripping blood ASCII headers, crimson terminal panels, candle vigils, ghost drift animations, and Día de los Muertos calavera artwork.

How Each Platform Is Used

Google Gemma — reasoning and generated writing

Gemma is SpookyCode's language model for code work and its supernatural character. The Pydantic AI agent uses it to inspect code through bounded tools, plan changes, edit only its isolated workspace, and interpret test failures. The same configured model chain also generates structured file eulogies, answers source-grounded questions during séances, reviews diffs, and supplies optional dynamic horror text. Google Cloud is the default provider; OpenRouter and Nvidia NIM can be selected or used through configured fallbacks.

Temporal — durable banishment

The spookycode banish <path> --temporal command submits a BanishWorkflow to the configured Temporal task queue. A Temporal worker runs the workflow's activities in safety order: seal files in the Crypt, verify their SHA-256 hashes, generate eulogies per file with activity retries, store the ofrendas, and only then remove the originals. The workflow result can be recovered and inspected if the CLI or worker is interrupted; the non-Temporal local path remains available too.

ElevenLabs — voices and horror sound design

The Haunted Machine registry defines the spoken lines and sound effects used for startup, séances, roasts, scans, banishment, and resurrection. ElevenLabs generates audio when credentials are configured; SpookyCode caches generated assets and plays cues asynchronously so playback does not block the coding workflow. If generation is unavailable, it writes procedural synthetic audio locally. The terminal's ghost, smoke, and blood visuals are rendered separately with Rich.

Sentry — agent and workflow observability

When SENTRY_DSN is configured, SpookyCode initializes the Sentry SDK and records agent runs as gen_ai.agent spans. Deterministic tool calls add breadcrumbs with tool names and relevant inputs/results; workflow steps add workflow.step spans, and raised exceptions are captured. This gives maintainers a trace of where an agent or banishment ritual failed without making Sentry a runtime requirement.

Why Does Open Innovation Matter?

Open innovation and open-weights models like Google Gemma were essential to building SpookyCode:

Code Sovereignty & Privacy: Codebases are among the most sensitive intellectual property in existence. Closed LLM APIs require sending proprietary logic to black-box servers. With open-weights models like Gemma, teams can run SpookyCode locally or in private VPCs with zero data leakage.
Standardized Interoperability: By pairing Gemma with OpenAI-compatible protocols and Pydantic AI, switching providers (from OpenRouter to Nvidia NIM or local self-hosted inference) requires changing just a single environment variable—no proprietary SDK vendor lock-in.
Reproducibility & Longevity: Code archiving requires decade-long stability. Open models ensure our undertaker agent can be summoned ten years from now without fear of deprecated proprietary endpoints or arbitrary pricing changes.

My Agent Session

Developing SpookyCode involved iterative agent-driven engineering:

Pair Programming & TDD: We wrote 37 automated unit tests covering crypt hashing, Temporal workflows, AST symbol extraction, Sentry tracing, and safety wards.
Durable Retry Architecture: We resolved event loop conflicts by turning Temporal activities into plain synchronous functions executed via thread pools.
Interactive Verification: Live séance sessions were tested to ensure Gemma accurately quoted vaulted functions rather than hallucinating syntax.

The Spirit of It

The defining moment of this project happened during testing on a deprecated 400-line legacy authentication script:

"Here lies mortal_auth.py. Born during an emergency refactor four years ago, it bore the burden of salted hashes and deprecated session cookies across 312 mortal lines without complaint. Rest peacefully beneath marigolds in the crypt; modern OAuth has claimed your watch."

When we subsequently entered the séance and asked the ghost:
"What was your secret key salt?"
The ghost accessed its vaulted memory via read_vault_code and replied:
"Ah, mortal... I remember line 14: SALT_PEPPER_V1. It kept the brute-force demons at bay through many cold nights. May your new tokens serve you as faithfully as I did."

It transformed a routine tech-debt cleanup into a moment of genuine reverence and developer joy.

Prize Categories

🌟 1. Best Use of Google Gemma ($200)

SpookyCode uses Google Gemma (google/gemma-4-31b-it:free via OpenRouter and google/gemma-4-31b-it via Nvidia NIM) as its primary reasoning engine. Gemma powers the undertaker agent, the structured EulogyRecord generation, the PR diff roaster, and the interactive séance ghost channeling with deep AST contextual grounding.

⏳ 2. Best Use of Temporal ($100)

SpookyCode orchestrates codebase banishment via a durable Temporal Workflow (BanishWorkflow). Banishment requires atomic guarantees: files are never deleted unless the crypt is byte-verified. With granular per-file activities, Temporal handles individual LLM rate-limits or failures gracefully without aborting the entire ritual. Includes a turnkey worker daemon (spookycode worker) and --temporal CLI flag.

🍃 3. Best Use of MongoDB Atlas ($100)

SpookyCode stores the eternal graveyard of dead code in MongoDB Atlas (pymongo). Each ofrenda document is indexed by session ID, filepath, and burial timestamp with upsert semantics and sanitized regex search, enabling developers to search and hold séances with code banished months ago.

🎙️ 4. Best Use of ElevenLabs ($100)

SpookyCode integrates ElevenLabs for atmospheric audio. From solemn Victorian funeral bell tolls to spectral whispers and eerie PR roast laughs, ElevenLabs audio is synthesized, cached, and played asynchronously in the background for zero-latency terminal immersion.

“Rest in peace, mortal syntax. The Crypt remembers.” 🕯️⚰️

DEV Community