🤔 Why PHANTOM?

• Zero-Config Tool Execution: Tools automatically install system dependencies and parse outputs cleanly, so the AI never gets stuck missing a library.
• Unbounded Agent Loops: Unlike standard chat UIs, PHANTOM allows the LLM to call tools recursively until the goal is achieved without needing constant human prompting.
• Persistent Context: The integrated SQLite memory store gives your agent long-term recall across sessions, preventing repetitive scanning or reconnaissance.

✨ Features

Feature	Description
🛡️ Multi-Agent Defense	Orchestrator, Planner, and Specialist Agents (Log, Compliance, Threat Modeler) working in parallel via Task Graphs
🤖 Any LLM Backend	OpenAI, OpenRouter, Ollama, LM Studio, DeepSeek, Claude — any OpenAI-compatible API
⚡ Real-Time Streaming	Live tool execution output, typing animations, and AI thinking display
🔓 Unlimited Operations	No tool call limits — PHANTOM runs autonomously until the task is done
🧠 Self-Improving	Creates its own tools, saves execution traces, learns from past runs
🔑 Secure Sudo	One-time sudo password with system validation — persisted securely
📁 Workspace System	Configurable workspace directory for scripts, reports, and file operations
🧩 MCP Server Hub	Native Model Context Protocol infrastructure supporting typed JSON schemas and rate-limited endpoints
📦 Skills System	Trust-tiered SKILL.md packages utilizing isolated-vm sandboxing
🌐 Web Research	Built-in web search and webpage scraping for real-time information
🕷️ Scrapling Integration	Anti-bot bypass, Cloudflare solving, JS rendering via Scrapling
💾 Semantic Memory	Local Vector Search (@xenova/transformers) paired with standard FTS
🛑 Emergency Stop	Instant abort button to halt any running operation
🎨 Premium Dark UI	Includes live animated Canvas graph of multi-agent communication

🚀 Quick Start

Prerequisites

• Node.js 18+ (install)
• Python 3.10+ (for Scrapling integration)
• npm (comes with Node.js)
• Any OpenAI-compatible API key
• Docker (Optional, for containerized usage)

Installation

# Clone the repository
git clone https://github.com/OmYarewar/PHANTOM.git
cd PHANTOM

# Install dependencies
npm install

# Configure your API
cp .env.example .env

Configuration

Edit .env with your API provider:

# OpenAI
API_BASE_URL=https://api.openai.com/v1
API_KEY=sk-your-key-here
MODEL_ID=gpt-4o

# OpenRouter (access to 100+ models)
API_BASE_URL=https://openrouter.ai/api/v1
API_KEY=sk-or-your-key-here
MODEL_ID=deepseek/deepseek-chat

# Ollama (local, free)
API_BASE_URL=http://localhost:11434/v1
API_KEY=ollama
MODEL_ID=llama3

# LM Studio (local)
API_BASE_URL=http://localhost:1234/v1
API_KEY=lm-studio
MODEL_ID=your-model-name

Run

npm run dev # START

Open http://localhost:5173 in your browser. That's it! 🎉

Docker

You can also run PHANTOM using Docker Compose:

docker compose up --build

Open http://localhost:3000 in your browser.

🏗️ Architecture

PHANTOM/
├── server/                 # Backend (Express + WebSocket)
│   ├── ai/
│   │   ├── llm-client.js   # LLM communication & streaming
│   │   └── system-prompt.js # Dynamic system prompt builder
│   ├── tools/
│   │   ├── executor.js      # Tool execution engine (14 tools)
│   │   └── registry.js      # Tool definitions for function calling
│   ├── memory/
│   │   └── store.js         # SQLite persistence layer
│   ├── routes/
│   │   └── api.js           # REST API endpoints
│   ├── config.js            # Configuration management
│   └── index.js             # Server entry point
├── frontend/               # Frontend (Vanilla JS + Vite)
│   ├── css/styles.css       # Dark theme design system
│   ├── js/
│   │   ├── app.js           # Main controller & WebSocket
│   │   ├── chat.js          # Chat rendering & animations
│   │   ├── settings.js      # Settings panel
│   │   ├── management.js    # MCP & Skills management
│   │   └── markdown.js      # Markdown renderer
│   └── index.html           # Main page
├── workspace/              # AI workspace (scripts, reports, skills)
├── .env.example            # Configuration template
├── vite.config.js          # Vite dev server config
└── package.json

🛠️ Available Tools

PHANTOM has 15 built-in tools that the AI uses autonomously:

Tool	Purpose
execute_command	Run shell commands with auto sudo injection
read_file	Read file contents
write_file	Write/create files
list_directory	List directory contents
install_tool	Auto-install packages (apt/pacman/pip/npm/go/cargo)
web_request	HTTP requests for recon & API testing
search_web	Web search via DuckDuckGo
scrape_webpage	Fetch & parse webpage content
scrapling_fetch	⭐ Advanced scraping — anti-bot bypass, Cloudflare, JS rendering (Scrapling)
python_execute	Execute Python code directly
save_memory	Store findings to persistent memory
recall_memory	Search persistent memory
edit_source_code	Self-modify PHANTOM's own code
save_trace	Log execution traces for self-optimization

🔒 Security Notes

• Sudo passwords are stored in a local SQLite database on your machine only
• API keys are stored locally and never transmitted except to your configured API endpoint
• The .env file and phantom.db are excluded from git
• PHANTOM runs locally only — no external telemetry or data collection
• The edit_source_code tool only works within the project directory and creates backups

🎨 Screenshots

Click to expand

Main Interface

The dark-themed command center with matrix background, real-time streaming, and AI thinking display.

Settings Panel

Configure API provider, model, temperature, workspace, and sudo access.

Management Panel

Manage MCP servers and skills with tabbed interface and .zip import.

⚙️ Settings (via Web UI)

All settings can be configured from the web UI and persist across restarts:

• API Configuration — Base URL, API key, model, temperature, max tokens
• Workspace — Default directory for all AI file operations
• Sudo Password — System-validated and securely stored
• MCP Servers — Add/remove Model Context Protocol servers
• Skills — Import .zip skill packages or let AI create them

🧠 How It Works

1. You ask — Type a request in the chat
2. AI thinks — Reasoning displayed in real-time (for supported models)
3. AI acts — Executes tools autonomously with live output streaming
4. AI reports — Clean, formatted results with typing animation
5. AI learns — Saves traces and memories for future optimization

PHANTOM implements ideas from Meta-Harness for automated harness optimization — the AI can review its own execution traces and improve its approach over time.

📋 API Endpoints

Endpoint	Method	Description
/api/settings	GET/PUT	Configuration management
/api/conversations	GET/POST	Conversation CRUD
/api/conversations/:id	GET/DELETE	Single conversation
/api/tools	GET	List available tools
/api/memory	GET	Query persistent memory
/api/mcp/servers	GET/POST/DELETE	MCP server management
/api/skills	GET	List installed skills
/api/skills/upload	POST	Import skill (.zip)
/api/sudo/validate	POST	Validate sudo password
/api/system/info	GET	System information
/ws	WebSocket	Real-time chat & streaming

🗺️ Roadmap

• MCP server integration
• Skills system with .zip import
• Persistent memory (SQLite)
• Multi-agent orchestration
• Semantic Vector Memory
• Docker support
• Web UI for memory visualization
• CVE database integration

📝 Changelog

v0.1.0 — Initial release: 15 tools, MCP support, streaming

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/awesome)
3. Commit your changes (git commit -m 'Add awesome feature')
4. Push to the branch (git push origin feature/awesome)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

⚠️ Disclaimer

PHANTOM is designed for authorized security testing only. Always obtain proper authorization before testing any systems. The developers are not responsible for misuse of this tool.

---