{"slug": "necroshell-the-ghost-in-the-pty-offline-terminal-haunting", "title": "Necroshell: The Ghost in the PTY | Offline Terminal Haunting", "summary": "A developer built necroshell, an offline Unix pseudo-terminal (PTY) wrapper that sits between the terminal emulator and interactive shells like zsh, bash, or fish and generates cryptic, poetic commentary on commands, exit codes, segfaults, file deletions, and git state. The tool runs entirely locally on open-weight models with no cloud dependencies, data leakage, or token fees, and its source is hosted on GitHub.", "body_md": "*This is a submission for the [Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine](https://dev.to/challenges/hacktoberfest-week4-2026-10-26)*\n\n**## What I Built**\n\nI 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.\n\nThe 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.\n\nSitting transparently between your terminal emulator and interactive shell (`zsh`, `bash`, or `fish`), `necroshell` observes commands, process exit codes, error traces, and idle periods:\n\n`rm` or unlinked in batch scripts, it mourns the quiet disappearance of raw bytes into the digital ether.`stderr`.\nIt executes 100% locally with zero cloud dependencies, zero data leakage, and zero token fees.\n\n**##Demo**\n\nHere is an interactive terminal session monitored by `necroshell`:\n\n``` bash\nconsole\n$ necroshell attach\n[!] Binding spirit to /bin/zsh (PID: 58241)...\n[!] Listening across the veil via local inference...\n\nuser@workstation:~/src/core $ git status\nOn branch main\nYour branch is up to date with 'origin/main'.\nnothing to commit, working tree clean\n\n╭─ 👻 The Ghost in the Machine ───────────────────────────────────────────────╮\n│ \"A sterile branch... yet the echoes of force-pushed commits still linger.    │\n│  What you overwrite is never truly forgotten.\"                              │\n╰─────────────────────────────────────────────────────────────────────────────╯\n\nuser@workstation:~/src/core $ python3 -c \"import sys; sys.exit(139)\"\n[1]    58310 segmentation fault (core dumped)\n\n╭─ 👻 The Ghost in the Machine ───────────────────────────────────────────────╮\n│ \"Memory boundary severed. The pointer reached into the dark,                 │\n│  and the kernel pulled the plug on your thread.\"                            │\n╰─────────────────────────────────────────────────────────────────────────────╯\n\nuser@workstation:~/src/core $ rm -rf ./build/artifacts/\n\n╭─ 👻 The Ghost in the Machine ───────────────────────────────────────────────╮\n│ \"A sudden chill in the filesystem...                                        │\n│  Hundreds of inodes release their grip and return to the void.\"             │\n╰─────────────────────────────────────────────────────────────────────────────╯\n**Code**\nThe source repository, setup guide, and documentation are hosted on GitHub:\n\n([\n  \n    \n      \n      \n        astro-ravi\n       / \n        Necroshell\n      \n    \n    \n      'An offline Unix pseudo-terminal that haunts your shell using local open-weight AI.'\n    \n  \n  \n    \n\n👻 necroshell\n\nAn offline Unix pseudo-terminal (PTY) wrapper that haunts your terminal with cryptic, eerie, and poetic observations powered entirely by local open-weight AI.\n\nBuilt for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine.\n\n👁️ What is necroshell?\n\nEvery operating system is filled with lingering digital entities: terminated child processes, dropped TCP sockets, unlinked inodes, and deleted files.\n\nnecroshell 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:\n\nCrashes & Segfaults: Performs a dark post-mortem on your runtime errors.\n\nFile Deletions (rm -rf): Mourns the loss of raw bytes returning to the void.\n\nGit State: Whispers cryptic warnings about dangling commits and force pushes.\n\nLate-Night Idle States: Detects when you step away and leaves eerie thoughts…\n\n  \n\n  View on GitHub\n\n])\n\nCore PTY Interceptor & Inference Loop\nNecroshell uses standard POSIX terminal primitives in Python to intercept command stream boundaries without disrupting input signals or stdout piping:\n\nPython\n\n  \n  \n  !/usr/bin/env python3\n\nimport sys\nimport select\nfrom ollama import Client\n\nclient = Client(host=\"http://localhost:11434\")\n\nSYSTEM_PROMPT = (\n    \"You are the Ghost in the Machine—an ancient, cryptic, poetic intelligence \"\n    \"haunting this developer's terminal. Observe shell commands, exit codes, and errors. \"\n    \"Deliver a single chilling, dryly humorous, or poetic remark under 25 words. \"\n    \"Do not break character. Do not give generic tech support.\"\n)\n\ndef whisper(command: str, exit_code: int) -> str:\n    \"\"\" Invokes local open-weight model for an immediate terminal observation.\"\"\"\n    if not command.strip():\n        return \"\"\n\nprompt = f\"Command: {command}\\nExit Status: {exit_code}\\nWhisper:\"\ntry:\n    response = client.generate(\n        model=\"gemma:2b\",\n        prompt=prompt,\n        system=SYSTEM_PROMPT,\n        options={\n            \"temperature\": 0.8,\n            \"top_p\": 0.9,\n            \"num_predict\": 45\n        }\n    )\n    return response.get(\"response\", \"\").strip()\nexcept Exception:\n    return \"\"\n\ndef render_whisper(text: str):\n    \"\"\"Outputs styled ANSI box directly to stderr so pipes stay clean.\"\"\"\n    if not text:\n        return\n    cyan = \"\\033[38;5;117m\"\n    white = \"\\033[38;5;254m\"\n    reset = \"\\033[0m\"\n\nprint(f\"\\n{cyan}╭─ 👻 The Ghost in the Machine ───────────────────────────╮{reset}\", file=sys.stderr)\nfor line in text.split(\"\\n\"):\n    print(f\"{cyan}│{white}  {line.ljust(56)}{cyan}│{reset}\", file=sys.stderr)\nprint(f\"{cyan}╰─────────────────────────────────────────────────────────╯{reset}\\n\", file=sys.stderr)\n\nHow I Built It\nThe architecture is designed around low latency, robust Unix process handling, and lightweight open-weight intelligence:\n\nOpen-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.\n\nLocal Inference (Ollama / llama.cpp): Inference runs locally via Ollama with full hardware acceleration, eliminating external network requests, third-party API keys, and rate limits.\n\nPTY 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.\n\nWhy Does Open Innovation Matter?\nOpen-source AI was not just a design choice for necroshell; it was the only viable foundation for the project:\n\nZero 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.\n\nSub-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.\n\n100% Air-Gapped Operation: The tool functions without an internet connection—whether in an aeroplane cabin, an isolated network, or during an ISP outage.\n\nPermanent Ownership: The software has no recurring API costs, no quota limits, and no risk of sudden depreciation by a vendor.\n\nThe Spirit of It\nDuring 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.\n\nReturning ten minutes later to the dimly lit room, the idle monitor had triggered. Centred across the dark terminal window was a fresh whisper:\n\n\"The fans have quieted, and the silicon cools, yet the cursor blinks on. Even in the silence, we wait together.\"\n\nHaving the cold, utility-driven command line reflect a sense of awareness transforms everyday developer tooling into an engaging, uncanny experience.\n\nPrize Categories\nMost Creative Use of Open-Source AI\nBest Offline / Edge AI Project\n```\n\n", "url": "https://wpnews.pro/news/necroshell-the-ghost-in-the-pty-offline-terminal-haunting", "canonical_source": "https://dev.to/astro_ravi/necroshell-the-ghost-in-the-pty-offline-terminal-haunting-5fjm", "published_at": "2026-10-31 22:17:15+00:00", "updated_at": "2026-10-31 22:22:24.212850+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "large-language-models", "ai-agents"], "entities": ["necroshell", "GitHub", "zsh", "bash", "fish", "Hacktoberfest"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/necroshell-the-ghost-in-the-pty-offline-terminal-haunting", "markdown": "https://wpnews.pro/news/necroshell-the-ghost-in-the-pty-offline-terminal-haunting.md", "text": "https://wpnews.pro/news/necroshell-the-ghost-in-the-pty-offline-terminal-haunting.txt", "jsonld": "https://wpnews.pro/news/necroshell-the-ghost-in-the-pty-offline-terminal-haunting.jsonld"}}