My Friend Copy-Pasted Random Commands From the Internet, So I Built an AI Ghost to Save His System

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

🔗 Live Demo: https://client-one-rosy-53.vercel.app/ 💻 GitHub Repository: https://github.com/CyborgX-hash/terminal-poltergeist

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.

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.

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.

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.

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

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

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

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.

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.

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.

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.

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.

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.

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

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.

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

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.

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.

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.

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.

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.”

🔗 Try the Live Application: https://client-one-rosy-53.vercel.app/ 💻 Explore the Source Code: https://github.com/CyborgX-hash/terminal-poltergeist

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