PhantomShell

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

👻 PhantomShell: The Ghost Living Inside Your Terminal

What if your terminal could tell you when something strange was happening inside your machine?

Not through a cloud-powered chatbot. Not through fabricated security alerts. But through a local AI model that can observe selected system activity, explain suspicious patterns, and narrate the events like a ghost haunting your computer.

Meet PhantomShell — a local-first, AI-powered haunted terminal that combines open-weight AI, system monitoring, and explainable security detection in one spooky experience.

What I Built

PhantomShell is my interpretation of Ghost in the Machine: a digital ghost that inhabits your terminal and helps you understand what your computer is doing behind the scenes.

Traditional terminals show commands and output. Security monitoring tools show events and alerts. PhantomShell adds another layer: a local AI investigator that explains what happened, why an event was flagged, and what you should investigate next.

Imagine seeing this in your terminal:

╔═══════════════════════════════════════╗
║          PHANTOMSHELL v1.0             ║
║        THE MACHINE IS WATCHING         ║
╚═══════════════════════════════════════╝

[PHANTOM DETECTED]

Something has changed inside your workspace.

Observation: Unusual file-change activity
Evidence: Multiple file modifications detected
Rule: File Change Burst
Risk: Medium

THE GHOST SPEAKS:

"I heard something moving in the dark.
Several files changed in a short interval.
Perhaps it was you... but perhaps you
should investigate."

Suggested action: Inspect the event timeline.

The spooky narration is generated by AI, but the underlying evidence and risk assessment come from the application's monitoring engine. The ghost should never invent events or claim that an ordinary anomaly proves malware is present.

Key features

• Haunted Terminal: An atmospheric terminal interface with live event updates, subtle glitch effects, and ghostly narration.
• Local AI Investigator: Ask questions about observed events and receive explanations grounded in available evidence.
• Real-Time Monitoring: Observe selected process metadata and file-system activity in an explicitly enabled workspace.
• Explainable Detection: Deterministic rules identify suspicious patterns and show exactly why an alert was triggered.
• Incident Timeline: Investigate events, compare timestamps, inspect evidence, and understand the sequence of activity.
• Offline-First AI: Run inference locally through Ollama after downloading the model and dependencies.
• Controlled Demo Mode: Demonstrate reproducible scenarios without pretending simulated events are real system activity.

The goal isn't to claim that PhantomShell can magically detect every threat. It's to make local system activity easier to understand through a memorable AI experience.

Code

The project is designed around a modular architecture:

PhantomShell
├── React + Vite frontend
│   ├── Haunted Terminal
│   ├── Incident Dashboard
│   ├── Event Timeline
│   └── AI Investigator
│
├── FastAPI backend
│   ├── Event Collectors
│   ├── Detection Engine
│   ├── Risk Scoring
│   ├── Incident Storage
│   └── WebSocket Streaming
│
├── Local AI Layer
│   ├── Ollama
│   ├── Open-Weight LLM
│   ├── Constrained Agent Harness
│   └── Evidence-Grounded Explanations
│
└── SQLite
    └── Local Event and Incident History

The frontend handles visualization and interaction. The backend collects permitted events, applies detection rules, stores incident metadata, and communicates with the local model.

The AI layer is deliberately separated from the detection engine so the application can continue to function when the model is unavailable.

How I Built It

I designed PhantomShell around three core components.

1. Local system monitoring

The backend uses Python, FastAPI, and psutil to inspect permitted process metadata. A file-system watcher observes an explicitly selected directory.

Events are normalized into a common structure before being passed to the detection engine.

The application is designed to avoid unrestricted shell access, hidden monitoring, and automatic destructive actions. Monitoring is opt-in, and demo events remain clearly separated from live telemetry.

2. An explainable detection engine

Rather than asking an LLM to decide whether everything is malicious, PhantomShell uses deterministic rules to identify patterns such as unusual file-change bursts, repeated failed operations, and attempted operations outside an authorized workspace.

Each finding should contain its triggering rule, supporting evidence, timestamp, and risk assessment.

This separation matters: a language model can generate a convincing explanation for an event that never happened. PhantomShell is designed to ground its narration in actual observations instead.

3. An open-weight model running locally

The planned default model is Qwen3 1.7B, served through Ollama.

The model receives structured incident information and responds in the voice of THE GHOST: mysterious, concise, and slightly unsettling.

A constrained agent harness provides read-only tools for retrieving recent events, inspecting incident details, listing detection rules, and summarizing the monitored system.

It cannot independently execute arbitrary shell commands or modify files.

The rest of the stack includes:

• React, Vite, TypeScript, Tailwind CSS: Frontend application.
• Framer Motion: Subtle interface and incident animations.
• FastAPI: Backend API and local service orchestration.
• WebSockets: Live event delivery.
• SQLite: Local incident and event metadata.
• Ollama + Qwen3: Local language-model inference.
• pytest: Backend and detection-engine testing.

The target is a laptop without a dedicated GPU. Actual performance will depend on available RAM, CPU, and model configuration.

Why Does Open Innovation Matter?

For PhantomShell, open innovation isn't simply a way to reduce API costs. It changes where the intelligence runs, who controls the data, and how the application can evolve.

Privacy without sacrificing intelligence

System activity can reveal sensitive information about a person's work, files, applications, and habits.

By running the language model locally, PhantomShell can explain monitored events without sending its telemetry to a hosted AI provider.

The ability to work offline

After downloading the model weights and application dependencies, the core monitoring, rule engine, event history, and local AI inference can operate without an internet connection.

That means the ghost can keep working even when the network disappears.

Models that can be changed

The AI layer is designed to be replaceable. Developers can experiment with different compatible open-weight models, compare the quality of explanations, and change the system's behavior without rebuilding the entire application around a proprietary API.

Transparent and reproducible detection

The monitoring rules are inspectable, the risk scoring is explicit, and the evidence behind each alert can be reviewed.

A judge or contributor can investigate why a finding occurred instead of relying on an opaque AI-generated verdict.

More accessible experimentation

Local inference removes mandatory per-request charges from a hosted LLM provider. The trade-offs are hardware requirements, model downloads, and local compute costs.

One important distinction: an open-weight model is not automatically open-source software under every definition. The specific model and dependency licenses must be checked and documented.

The central idea is simple: your machine's private activity should not need to leave your machine just to become understandable.

My Agent Session

I'd use this section to show the coding agent helping build the detection engine, integrating Ollama, or debugging the boundary between actual telemetry and AI-generated explanations.

The most valuable session would demonstrate the engineering decisions behind the project, not just the generation of boilerplate code.

The Spirit of It

There is something unsettling about a machine that seems to know when something has changed.

A new process appears. A group of files changes unexpectedly. An event triggers a rule you forgot existed.

And then a quiet voice explains what it observed.

That is the experience I want PhantomShell to create: the feeling that the machine has a memory of its own, while keeping the explanation grounded in evidence rather than pretending that a real supernatural presence exists.

The ghost is fictional. The events it describes are not.

For me, Ghost in the Machine is also about the invisible complexity inside the tools we use every day. Open-source AI gives us a way to explore that complexity without surrendering control of our data or the systems we build.

Prize Categories

Best Use of Gemma

Final Thoughts

PhantomShell is an experiment in making local AI both useful and memorable.

It combines the transparency of deterministic security rules, the flexibility of open-weight language models, and the atmosphere of a haunted terminal into an experience that can run on a personal machine.

No mandatory cloud inference. No paid LLM API dependency. No need to treat the model as an unquestionable authority.

Just a machine, its evidence, and a ghost that helps you understand what happened.

Sometimes the most interesting intelligence is the kind that stays inside the machine. 👻