Necroshell: The Ghost in the PTY | Offline Terminal Haunting

Ravi Ranjan — Sat, 31 Oct 2026 22:17:15 +0000

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

## What I Built

I built necroshell (The Ghost in the Machine), an offline Unix pseudo-terminal (PTY) monitor and shell companion that brings an eerie, autonomous spirit directly into your everyday command line.

The project takes a literal, tactile approach to the Ghost in the Machine theme. Every day, developers leave behind thousands of dead child processes, abandoned branches, deleted temporary buffers, and discarded lines of code. necroshell imagines that this accumulated digital debris coalesces into a brooding, observant entity bound directly to your local hardware registers and CPU cycles.

Sitting transparently between your terminal emulator and interactive shell (zsh, bash, or fish), necroshell observes commands, process exit codes, error traces, and idle periods:

Terminal Post-Mortems: When a process crashes with an unhandled exception, segfault, or non-zero exit code, the spirit delivers a cryptic autopsy on the fallen execution.
Mourning the Inodes: When files are removed via rm or unlinked in batch scripts, it mourns the quiet disappearance of raw bytes into the digital ether.
Quiet Night Haunting: When your shell sits completely idle late at night, the terminal pulses gently and pushes subtle, philosophical whispers straight to stderr.

It executes 100% locally with zero cloud dependencies, zero data leakage, and zero token fees.

##Demo

Here is an interactive terminal session monitored by necroshell:


console
$ necroshell attach
[!] Binding spirit to /bin/zsh (PID: 58241)...
[!] Listening across the veil via local inference...

user@workstation:~/src/core $ git status
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean

╭─ 👻 The Ghost in the Machine ───────────────────────────────────────────────╮
│ "A sterile branch... yet the echoes of force-pushed commits still linger.    │
│  What you overwrite is never truly forgotten."                              │
╰─────────────────────────────────────────────────────────────────────────────╯

user@workstation:~/src/core $ python3 -c "import sys; sys.exit(139)"
[1]    58310 segmentation fault (core dumped)

╭─ 👻 The Ghost in the Machine ───────────────────────────────────────────────╮
│ "Memory boundary severed. The pointer reached into the dark,                 │
│  and the kernel pulled the plug on your thread."                            │
╰─────────────────────────────────────────────────────────────────────────────╯

user@workstation:~/src/core $ rm -rf ./build/artifacts/

╭─ 👻 The Ghost in the Machine ───────────────────────────────────────────────╮
│ "A sudden chill in the filesystem...                                        │
│  Hundreds of inodes release their grip and return to the void."             │
╰─────────────────────────────────────────────────────────────────────────────╯
**Code**
The source repository, setup guide, and documentation are hosted on GitHub:

([
  
    
      
      
        astro-ravi
       / 
        Necroshell
      
    
    
      'An offline Unix pseudo-terminal that haunts your shell using local open-weight AI.'
    
  
  
    

👻 necroshell


An offline Unix pseudo-terminal (PTY) wrapper that haunts your terminal with cryptic, eerie, and poetic observations powered entirely by local open-weight AI.

Built for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine.





👁️ What is necroshell?


Every operating system is filled with lingering digital entities: terminated child processes, dropped TCP sockets, unlinked inodes, and deleted files.

necroshell imagines that these discarded fragments coalesce into an observant spirit bound directly to your machine's CPU and registers. Sitting between your terminal and shell (zsh, bash, or fish), it monitors standard POSIX events:






Crashes & Segfaults: Performs a dark post-mortem on your runtime errors.



File Deletions (rm -rf): Mourns the loss of raw bytes returning to the void.



Git State: Whispers cryptic warnings about dangling commits and force pushes.



Late-Night Idle States: Detects when you step away and leaves eerie thoughts…




  


  View on GitHub





])

Core PTY Interceptor & Inference Loop

Necroshell uses standard POSIX terminal primitives in Python to intercept command stream boundaries without disrupting input signals or stdout piping:

Python

  
  
  !/usr/bin/env python3


import sys

import select

from ollama import Client

client = Client(host="http://localhost:11434")

SYSTEM_PROMPT = (

    "You are the Ghost in the Machine—an ancient, cryptic, poetic intelligence "

    "haunting this developer's terminal. Observe shell commands, exit codes, and errors. "

    "Deliver a single chilling, dryly humorous, or poetic remark under 25 words. "

    "Do not break character. Do not give generic tech support."

)

def whisper(command: str, exit_code: int) -> str:

    """ Invokes local open-weight model for an immediate terminal observation."""

    if not command.strip():

        return ""

prompt = f"Command: {command}\nExit Status: {exit_code}\nWhisper:"
try:
    response = client.generate(
        model="gemma:2b",
        prompt=prompt,
        system=SYSTEM_PROMPT,
        options={
            "temperature": 0.8,
            "top_p": 0.9,
            "num_predict": 45
        }
    )
    return response.get("response", "").strip()
except Exception:
    return ""



def render_whisper(text: str):

    """Outputs styled ANSI box directly to stderr so pipes stay clean."""

    if not text:

        return

    cyan = "\033[38;5;117m"

    white = "\033[38;5;254m"

    reset = "\033[0m"

print(f"\n{cyan}╭─ 👻 The Ghost in the Machine ───────────────────────────╮{reset}", file=sys.stderr)
for line in text.split("\n"):
    print(f"{cyan}│{white}  {line.ljust(56)}{cyan}│{reset}", file=sys.stderr)
print(f"{cyan}╰─────────────────────────────────────────────────────────╯{reset}\n", file=sys.stderr)



How I Built It

The architecture is designed around low latency, robust Unix process handling, and lightweight open-weight intelligence:

Open-Weight Intelligence (gemma:2b / llama3.2:1b): Interactive developer tools need fast response times. Using a compact, 4-bit quantized open-weight model allows the entire weights matrix to sit permanently in less than 2 GB of RAM, generating observations in under 120ms.

Local Inference (Ollama / llama.cpp): Inference runs locally via Ollama with full hardware acceleration, eliminating external network requests, third-party API keys, and rate limits.

PTY Master/Slave Wrapper (pty, termios, tty): Instead of fragile shell aliases or .zshrc prompt hooks that break script pipelines, necroshell launches a true POSIX pseudo-terminal supervisor. It handles window resizing signals (SIGWINCH), captures exit states, and outputs callout boxes strictly through sys. stderr so UNIX standard output piping remains pristine.

Why Does Open Innovation Matter?

Open-source AI was not just a design choice for necroshell; it was the only viable foundation for the project:

Zero Compromise on Privacy: A developer's terminal regularly handles passwords, SSH tokens, secret keys, proprietary source code, and private file paths. Directing raw shell command buffers to a remote proprietary cloud API would be an unacceptable security compromise. With open-weight models running on local silicon, the command stream never leaves memory.

Sub-Second Local Latency: Waiting 1 to 3 seconds for a remote server round-trip breaks the tempo of the command line. Open weights running locally deliver instant, low-latency execution directly at the prompt.

100% Air-Gapped Operation: The tool functions without an internet connection—whether in an aeroplane cabin, an isolated network, or during an ISP outage.

Permanent Ownership: The software has no recurring API costs, no quota limits, and no risk of sudden depreciation by a vendor.

The Spirit of It

During a late-night coding session, a complex compilation step failed repeatedly. After a string of frustrating errors, I stepped away from my desk to take a break.

Returning ten minutes later to the dimly lit room, the idle monitor had triggered. Centred across the dark terminal window was a fresh whisper:

"The fans have quieted, and the silicon cools, yet the cursor blinks on. Even in the silence, we wait together."

Having the cold, utility-driven command line reflect a sense of awareness transforms everyday developer tooling into an engaging, uncanny experience.

Prize Categories

Most Creative Use of Open-Source AI

Best Offline / Edge AI Project

DEV Community: Ravi Ranjan

Necroshell: The Ghost in the PTY | Offline Terminal Haunting

astro-ravi / Necroshell

'An offline Unix pseudo-terminal that haunts your shell using local open-weight AI.'

👻 necroshell

👁️ What is necroshell?

!/usr/bin/env python3