Documentation | The Joker

Overview

The Joker is an Agentic Terminal — an AI-powered autonomous coding assistant built with TypeScript/Node.js that can execute complex coding tasks, scrape the web with stealth capabilities, generate complete project structures from natural language descriptions, run passive OSINT reconnaissance, and deploy applications with Docker and CI/CD pipelines.

Powered by LM Studio (local inference) and optionally by AirLLM (70B models on 4GB RAM), the Joker requires zero cloud services.

Requirement	Minimum	Recommended
Node.js	18.x	22.x
Memory	4 GB	8 GB
Storage	1 GB	5 GB
OS	Windows 10 / macOS 12 / Linux	Latest versions
LLM Server	Any OpenAI-compatible	LM Studio

Runtime Dependencies

Source: SPDX-2.3 bill-of-materials · com.github.ratna3/theJoker@master

Package	Version	Purpose
axios	^1.13.2	HTTP client — LM Studio & AirLLM API calls
cheerio	^1.1.2	Server-side HTML parsing for web scraping
chalk	^5.6.2	Terminal output colour formatting
chokidar	^5.0.0	File-system watcher for hot-reload & project monitoring
dotenv	^17.2.3	Environment variable loader (.env)
inquirer	^13.0.1	Interactive CLI prompts & backend selection
ora	^9.0.0	Terminal spinner for async operations
puppeteer	^24.31.0	Headless Chromium for stealth web scraping
puppeteer-extra	^3.3.6	Plugin framework wrapping Puppeteer
puppeteer-extra-plugin-stealth	^2.11.2	Anti-detection patches (webdriver, WebGL, plugins)
readline-sync	^1.4.10	Synchronous stdin for interactive terminal sessions
uuid	^13.0.0	Unique ID generation for sessions & tasks
winston	^3.18.3	Structured logging with file & console transports

Dev Dependencies

Package	Version	Purpose
typescript	^5.9.3	TypeScript compiler
ts-node	^10.9.2	Development hot-reload runner
ts-jest	^29.4.6	Jest TypeScript transformer
jest	^30.2.0	Test runner (980 tests, 22 suites)
eslint	^9.39.1	Linter
@typescript-eslint/eslint-plugin	^8.48.1	TypeScript ESLint rules
@typescript-eslint/parser	^8.48.1	TypeScript ESLint parser
prettier	^3.7.3	Code formatter
rimraf	^6.1.2	Cross-platform directory cleanup

Quick Start

# Clone the repository
git clone https://github.com/ratna3/theJoker.git
cd theJoker

# Install dependencies
npm install

# Copy environment config
cp .env.example .env
# Open .env and set LM_STUDIO_BASE_URL + LM_STUDIO_MODEL

# Build and run
npm run build
npm start

Start LM Studio and load a model (e.g. qwen2.5-coder-14b-instruct-uncensored) before running The Joker. The default server URL is http://localhost:1234.

Installation

Step-by-step

Clone or fork the repository from GitHub
Run npm install to install all dependencies
Copy .env.example to .env and configure
Open LM Studio, load your preferred model, start the local server
Run npm run build to compile TypeScript
Run npm start to launch The Joker

Development mode

# Hot reload with ts-node
npm run dev

# Watch mode TypeScript compilation
npm run build:watch

Docker

Quick Run

docker build -t thejoker .

docker run -it --rm \
  --env-file .env \
  -v ./projects:/app/projects \
  -v ./reports:/app/reports \
  --add-host=host.docker.internal:host-gateway \
  thejoker

Use host.docker.internal as LM_STUDIO_BASE_URL so the container can reach LM Studio running on your host machine.

Docker Compose

# Start detached
docker compose up -d

# Attach to the interactive terminal
docker attach thejoker

# Stop
docker compose down

Configuration

All configuration is done via a .env file in the project root.

# LM Studio
LM_STUDIO_BASE_URL=http://localhost:1234
LM_STUDIO_MODEL=qwen2.5-coder-14b-instruct-uncensored
LM_STUDIO_API_KEY=not-needed

# Agent
AGENT_MAX_ITERATIONS=10
AGENT_TIMEOUT_MS=60000
AGENT_VERBOSE=true

# Scraper
SCRAPER_HEADLESS=true
SCRAPER_TIMEOUT_MS=30000

# AirLLM (optional)
AIRLLM_MODEL=garage-bAInd/Platypus2-70B-instruct
AIRLLM_PORT=8899
AIRLLM_MAX_LENGTH=512
AIRLLM_COMPRESSION=none     # none | 4bit | 8bit
AIRLLM_PYTHON_PATH=python

# Logs
LOG_LEVEL=info

AirLLM Setup

AirLLM enables running 70B-parameter models on as little as 4GB GPU RAM using layer-wise inference. Each transformer layer is loaded to GPU on demand, processed, then offloaded.

Inference is slow (30–120s per response). AirLLM is best for occasional heavy queries — switch back to LM Studio for fast iteration.

Setup

# Install Python requirements
pip install -r requirements-airllm.txt

# Inside The Joker, switch backend:
joker > airllm
joker > airllm meta-llama/Llama-2-70b-chat-hf

# Check status
joker > airllm-status

# Revert to LM Studio
joker > airllm-stop

Vibe Coding

Describe the app you want in plain English and The Joker builds it end-to-end — from framework scaffolding to file generation to dependency install to launching a dev server.

joker > vibe Build me a portfolio website with dark mode and a contact form

# 🧠 Analyzing your idea...
# 📁 Scaffolding React project: portfolio-website
# 🧬 Generating 6 components, 3 pages
# 📝 Writing 9 files
# 📦 Installing dependencies...
# 🚀 Starting dev server...
# 🚀 App live at: http://localhost:3000

# Refine the running app:
joker > vibe Add a skills section with animated bars

# Stop the dev server:
joker > vibe-stop

Command	Aliases	Description
vibe <description>	build, create-app	Build a complete app from natural language
vibe-stop	stop-dev	Stop the running dev server

Supported frameworks

React · Next.js · Vue · Express · Node.js (auto-detected from description)

OSINT Recon

One command performs comprehensive passive reconnaissance on a domain — no active scanning, no noise.

joker > recon example.com
# aliases: scan, osint, investigate

# Output:
# 📡 DNS (A, AAAA, MX, TXT, NS, CNAME, SOA)
# 🔎 WHOIS (registrar, dates, nameservers)
# 🔐 SSL/TLS (certificate, issuer, expiry)
# 📋 HTTP Headers (security analysis)
# 🏗️ Tech Stack (25+ signatures)
# 📧 Emails from /contact, /about, /team
# 🔗 Social links
# 📸 Full-page screenshot
# 🛡️ Security Score: /100
# 📄 Report → ./reports/<domain>-recon.md

Web Scraping

Puppeteer-based stealth browser that removes all bot detection fingerprints.

joker > scrape https://example.com
joker > search best programming languages 2025
joker > Extract all links from https://github.com/trending

Evasion	Description
navigator.webdriver	Removed — no automation trace
chrome.runtime	Faked Chrome runtime properties
navigator.plugins	Faked plugin array
WebGL vendor/renderer	Realistic GPU spoofing
User-Agent	Consistent modern browser UA

TUI Dashboard

A full-screen interactive terminal dashboard built with blessed.

joker > tui   # aliases: dashboard, ui

Key	Action
Tab	Cycle through panes
q	Quit dashboard
c	Clear output
i / Enter	Focus input
Esc	Back / unfocus

Built-in Commands

Command	Aliases	Description
help	—	Show all commands with examples
clear	cls	Clear terminal
exit	quit, q	Exit The Joker
history	—	Show command history
banner	—	Show welcome banner
vibe	build, create-app	Build app from natural language
vibe-stop	stop-dev	Stop dev server
recon	scan, osint, investigate	OSINT recon on domain
tui	dashboard, ui	Toggle TUI dashboard
airllm	air, 70b	Switch to AirLLM backend
airllm-stop	air-stop	Revert to LM Studio
airllm-status	air-status	Show AirLLM sidecar status
memory	mem	Show agent memory stats
agent-status	—	Show agent state
reset-agent	—	Reset agent state

Testing

npm test                                   # Run all tests
npm run test:coverage                      # With coverage report
npm run test:watch                         # Watch mode
npm test -- --testPathPatterns="parser"    # Single suite

Suite	Tests	Status
Agent System	120+	✅ Passing
LLM Integration	80+	✅ Passing
Web Scraper	90+	✅ Passing
Tools	100+	✅ Passing
CLI	80+	✅ Passing
Error Handling	70+	✅ Passing
Project Management	100+	✅ Passing
Utilities	150+	✅ Passing
Total	980	✅ All Passing

Security

DO NOT create public GitHub issues for security vulnerabilities. Report them privately to ratnakirtiscr@gmail.com.

See SECURITY.md for the full responsible disclosure policy.