朋友從網上亂貼命令後，我打造 Terminal Poltergeist 這個 AI 終端安全助手

“Before you hit Enter, let the ghost reveal what lies beneath.”

👻 What I Built

Terminal Poltergeist is an AI-powered shell command analysis and developer safety assistant that combines an open-weight language model with a deterministic security rule engine.

Developers frequently copy commands from Stack Overflow, GitHub repositories, documentation, and CI/CD pipelines without fully understanding their consequences. A misplaced flag, an unexpected pipe, or an incorrect filesystem path can turn an ordinary command into a destructive operation.

I wanted to build something that helps developers understand these commands before they run them.

Inspired by the Ghost in the Machine theme, I imagined a spectral guardian living inside the terminal—a ghost that examines unfamiliar commands, uncovers hidden dangers, explains cryptic flags, detects common typos, and suggests safer alternatives.

That idea became Terminal Poltergeist: a haunted command-analysis experience that turns developer uncertainty into understanding.

Its most important rule: submitted commands are NEVER executed. They are treated as untrusted input and analyzed using static parsing, deterministic security checks, and AI inference.

✨ What Can It Do?

👻 1. Haunted Terminal Experience

The interface combines a dark Halloween aesthetic with a retro terminal atmosphere, featuring CRT scanlines, spectral glows, glowing command prompts, subtle animations, and spooky developer-themed commentary.

🔍 2. AI-Powered Command Autopsy

Submit a shell command and receive a detailed breakdown of its behavior, flags, arguments, potential side effects, and possible risks. The AI also suggests safer alternatives when appropriate.

🛡️ 3. Deterministic Security Guardrails

A JavaScript-based rule engine identifies known dangerous command patterns independently of the language model.

When a recognized hazard is detected, the engine enforces an appropriate minimum severity so that a reassuring AI response cannot override a known security risk.

🕸️ 4. Curated Demo Incantations

Explore predefined examples covering:

• Fork bombs and recursive deletion.
• Dangerous filesystem permissions.
• Raw disk writes and formatting operations.
• Remote scripts piped directly into a shell.
• Common command typos, such as gti instead of git.
• Non-existent commands and phantom binaries.

These examples let users explore different scenarios without executing any commands.

🧩 5. Component-Level Breakdown

The analyzer presents command components—including flags, arguments, and pipe operators—in an understandable format, helping developers see how complex commands are constructed.

📜 6. Session History Dashboard

Review previous analyses within an isolated anonymous session, inspect risk levels, and explore the distribution of security findings.

⚙️ How I Built It

Terminal Poltergeist uses a dual-defense architecture that combines open-weight AI with deterministic security rules.

Instead of relying entirely on an AI model, the application combines static command analysis, predefined security rules, and AI-generated explanations to produce a more informative security report.

Architecture Overview

🧠 1. Open-Weight AI Inference

I integrated openai/gpt-oss-20b through Groq's hosted inference API.

The model helps explain shell commands in plain language, break down flags and compound operations, identify contextual risks, and suggest safer alternatives. It also adds the project's signature spooky developer commentary.

Using hosted inference allowed me to integrate an open-weight model without hosting model weights or maintaining GPU infrastructure.

🛡️ 2. Deterministic Security Guardrails

Language models can hallucinate, overlook dangerous command patterns, or be influenced by adversarial text embedded in user input. For this reason, I did not rely on AI alone for security decisions.

The deterministic JavaScript rule engine checks for known hazardous patterns, including:

• Fork bombs: Recursive shell constructs that can exhaust system resources.
• Root filesystem destruction: Dangerous recursive deletion patterns and relevant flags.
• Raw disk operations: Potentially destructive writes and filesystem formatting.
• Privilege and permission risks: Insecure recursive permission changes and modifications to sensitive system configuration.
• Remote code execution patterns: Downloading scripts and immediately piping them into a shell.

When a recognized hazard is detected, the rule engine applies a minimum severity appropriate to that rule. The AI contributes contextual analysis, but it cannot downgrade a known hazard below its enforced severity.

This approach makes the security logic more inspectable, testable, and predictable than relying on an AI-generated risk score alone.

👾 3. Phantom Binary and Typo Detection

Not every failed command is a security threat. A misspelled command typically produces a command-not-found error rather than executing successfully.

Terminal Poltergeist distinguishes likely missing commands from dangerous operations by checking known utilities, common developer tools, and likely command typos.

Examples include:

• gti → possible correction: git
• sl → possible correction: ls
• foobar123 → possible command-not-found result

When the tool identifies a likely missing command, it displays a dedicated COMMAND NOT FOUND status card rather than automatically treating the input as malicious.

These suggestions are advisory and depend on the available command knowledge and analysis context.

🧰 4. Technology Stack

• Frontend: React, Vite, Tailwind CSS
• Backend: Node.js, Express.js
• Database layer: Prisma ORM with PostgreSQL support
• AI: GPT-OSS 20B through Groq
• Security: Static lexical analysis and deterministic JavaScript rules
• Testing: Automated unit and integration tests

The repository is organized as a monorepo, with separate client/ and server/ applications.

🧪 5. Testing and Reliability

The project includes 37 automated unit and integration tests covering lexical parsing, security rules, phantom command detection, and prompt-injection defenses.

The goal is to make the application more than a themed AI wrapper: the core safety checks should be inspectable, testable, and independently maintained.

Most importantly, submitted commands are never executed. They are treated as untrusted input and analyzed as data. The application provides advisory security findings rather than guaranteeing that any command is completely safe.

🌍 Why Open Innovation Matters

Open innovation is especially valuable when building developer-facing security tools.

🔓 1. Model Choice and Reduced Vendor Lock-In

By separating inference from the application logic, the project can be adapted to compatible model providers. This creates a path toward local inference with tools such as Ollama or self-hosted inference servers, subject to model compatibility and available hardware.

🔍 2. Transparent, Inspectable Security Logic

The deterministic rule engine can be reviewed, tested, and extended by contributors. Known dangerous patterns do not have to be entrusted entirely to a black-box language model.

🌱 3. Accessibility for Independent Developers

Hosted open-weight inference lets me experiment with capable models without maintaining GPU infrastructure. A future local-inference option could also make the tool more accessible to developers who prefer to run models on their own hardware.

🔐 4. A Foundation for Privacy-Conscious Tooling

Shell commands can contain internal paths, credentials, and infrastructure details. The application should minimize the information sent to external services, avoid unnecessary retention, and make its processing model clear to users.

The current version uses hosted inference, so AI analysis requires an internet connection and submitted analysis data may be processed by the inference provider. Local inference remains a potential future extension rather than a capability I claim the current deployment already provides.

For me, open innovation is not just about choosing an open-weight model. It is about making the surrounding system adaptable, inspectable, and open to improvement.

👻 The Spirit of the Machine

Every developer knows that moment of hesitation before pressing Enter.

You have copied a command from somewhere on the internet. It looks correct. You think you understand it. But one flag, one path, or one pipe could change everything.

Terminal Poltergeist is built around that moment.

It gives developers a place to pause, investigate, and understand before taking action. The ghost is more than a Halloween character: it represents the hidden behavior inside commands that we often execute without fully understanding.

By combining open-weight AI with deterministic security guardrails, I wanted to make command-line safety more approachable without pretending that AI can guarantee perfect protection.

“The terminal may be mysterious. Your commands shouldn't be.”

🏆 Challenge Tracks

• Primary Track: Ghost in the Machine — Hacktoberfest Open-Source AI Challenge
• Additional Track: Open-Weight AI Innovation

Built with curiosity, open-source AI, and a little bit of digital haunting. 👻