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

Posted on Oct 30 • Originally published at github.com

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

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.

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

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 Enter fullscreen mode Exit fullscreen mode 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!

Enter fullscreen mode Exit fullscreen mode 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

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 Enter fullscreen mode Exit fullscreen mode How I Built It SpookyCode was engineered around modern open-source AI, agentic architectures, and durable systems:

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:

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.

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.

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

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.

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.

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.

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.

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.

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

Developing SpookyCode involved iterative agent-driven engineering:

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

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.

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.

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.

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.

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.” 🕯️⚰️