🃏 The Joker - Agentic Terminal

An autonomous AI-powered terminal that understands natural language queries, scrapes the web intelligently, generates complete projects, and deploys applications.

Powered by LM Studio's qwen2.5-coder-14b-instruct-uncensored model

---

📖 Table of Contents

• Features
• Quick Start
• Installation
• Configuration
• Usage
• Architecture
• Built-in Commands
• Available Tools
• Development
• Testing
• Contributing
• License

---

✨ Features

Category	Features
🧠 AI Agent	Natural language understanding, autonomous task execution, self-correction
🌐 Web Scraping	Puppeteer-based scraping with stealth mode and anti-detection
📁 Project Generation	Create complete projects from natural language descriptions
🚀 Deployment	Docker, Kubernetes, and CI/CD pipeline automation
💾 Memory	Persistent context across sessions with intelligent summarization
🎨 CLI	Beautiful terminal UI with rich formatting and progress indicators
🔄 Error Handling	Retry logic, circuit breakers, and graceful degradation
🧪 Testing	966 tests with 80%+ coverage across 22 test suites

---

🚀 Quick Start

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

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Start LM Studio with qwen2.5-coder-14b-instruct-uncensored
# Make sure it's running at http://xxx.xxx.xx.x:xxxx

# Build and run
npm run build
npm start

---

📦 Installation

Prerequisites

• Node.js 18.x or higher
• npm 9.x or higher
• LM Studio with a compatible model loaded
• Windows/Linux/macOS with Puppeteer support

Step-by-Step Installation

1. Clone the repository

   git clone https://github.com/yourusername/theJoker.git
   cd theJoker

2. Install dependencies

   npm install

3. Configure environment

   cp .env.example .env
   # Edit .env with your LM Studio endpoint

4. Build the project

   npm run build

5. Start LM Studio

   • Open LM Studio
   • Load qwen2.5-coder-14b-instruct-uncensored (or similar model)
   • Start the local server at http://192.xxx.xx.x:xxxx

6. Run The Joker

   npm start

---

⚙️ Configuration

Environment Variables

Create a .env file in the project root:

# LM Studio Configuration
LM_STUDIO_ENDPOINT=http://xxx.xxx.xx.x:xxxx
LM_STUDIO_MODEL=qwen2.5-coder-14b-instruct-uncensored

# LLM Settings
LLM_TEMPERATURE=0.7
LLM_MAX_TOKENS=4096
LLM_TIMEOUT=60000

# Puppeteer Configuration
PUPPETEER_HEADLESS=true
PUPPETEER_TIMEOUT=30000

# Application Settings
DEBUG_MODE=false
LOG_LEVEL=info
MAX_RETRIES=3
CACHE_TTL=300000

Configuration File

Additional settings can be configured in config/default.json:

{
  "llm": {
    "endpoint": "http://xxx.xxx.xx.x:xxxx",
    "model": "qwen2.5-coder-14b-instruct-uncensored",
    "temperature": 0.7,
    "maxTokens": 4096
  },
  "scraper": {
    "headless": true,
    "timeout": 30000,
    "userAgentRotation": true
  },
  "agent": {
    "maxIterations": 10,
    "memoryPersistence": true
  }
}

---

📝 Usage

Interactive Mode

Start The Joker in interactive mode:

npm start

You'll see the welcome banner:

╔═══════════════════════════════════════════╗
║                                           ║
║   🃏  THE JOKER - Agentic Terminal  🃏     ║
║                                           ║
║   Powered by qwen2.5-coder-14b            ║
║   Type your query or 'help' for commands  ║
║                                           ║
╚═══════════════════════════════════════════╝

🃏 Joker >

Example Queries

Find Information:

🃏 Joker > Find the top 5 programming languages in 2024

Search for Places:

🃏 Joker > Find best places to eat in Chicago

Scrape a Website:

🃏 Joker > Extract all links from https://example.com

Compare Items:

🃏 Joker > Compare React vs Vue for web development

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────────────┐
│                           THE JOKER TERMINAL                                    │
├─────────────────────────────────────────────────────────────────────────────────┤
│  ┌─────────────┐    ┌──────────────┐    ┌─────────────────────┐                │
│  │  User Input │───▶│ Intent Parser│───▶│   Agent Planner     │                │
│  │   (CLI)     │    │   (LLM)      │    │   (LLM + Tools)     │                │
│  └─────────────┘    └──────────────┘    └──────────┬──────────┘                │
│                                                     │                           │
│  ┌──────────────────────────────────────────────────▼─────────────────────────┐│
│  │                          TOOL EXECUTOR                                      ││
│  │  ┌─────────────────────────────────────────────────────────────────────┐   ││
│  │  │  WEB SCRAPING TOOLS                                                  │   ││
│  │  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐            │   ││
│  │  │  │   Web    │  │Puppeteer │  │   Data   │  │   Link   │            │   ││
│  │  │  │  Search  │  │ Scraper  │  │Processor │  │Extractor │            │   ││
│  │  │  └──────────┘  └──────────┘  └──────────┘  └──────────┘            │   ││
│  │  └─────────────────────────────────────────────────────────────────────┘   ││
│  └─────────────────────────────────────────────────────────────────────────────┘│
│                                                     │                           │
│  ┌──────────────────────────────────────────────────▼─────────────────────────┐│
│  │                       OUTPUT FORMATTER                                      ││
│  │     Structured Results + Code + Links + Files + Terminal Display           ││
│  └─────────────────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────────────────┘

Directory Structure

theJoker/
├── src/
│   ├── index.ts                 # Entry point
│   ├── cli/
│   │   ├── terminal.ts          # Terminal interface
│   │   ├── commands.ts          # Command handlers
│   │   ├── display.ts           # Output formatting
│   │   ├── progress.ts          # Progress tracking
│   │   └── formatter.ts         # Result formatting
│   ├── agents/
│   │   ├── agent.ts             # Main agent loop
│   │   ├── planner.ts           # Action planning
│   │   ├── executor.ts          # Tool execution
│   │   └── memory.ts            # Session memory
│   ├── llm/
│   │   ├── client.ts            # LM Studio API client
│   │   ├── prompts.ts           # Prompt templates
│   │   ├── parser.ts            # Response parsing
│   │   └── summarizer.ts        # LLM summarization
│   ├── scraper/
│   │   ├── browser.ts           # Puppeteer setup
│   │   ├── navigator.ts         # Page navigation
│   │   ├── extractor.ts         # Data extraction
│   │   └── stealth.ts           # Anti-detection
│   ├── tools/
│   │   ├── registry.ts          # Tool registry
│   │   ├── search.ts            # Web search tool
│   │   ├── scrape.ts            # Scraping tool
│   │   └── process.ts           # Data processing
│   ├── errors/
│   │   ├── handler.ts           # Error handling
│   │   ├── retry.ts             # Retry logic
│   │   └── circuit-breaker.ts   # Circuit breaker
│   ├── utils/
│   │   ├── logger.ts            # Logging
│   │   ├── config.ts            # Configuration
│   │   ├── cache.ts             # Caching utilities
│   │   ├── cleaner.ts           # Data cleaning
│   │   ├── links.ts             # Link validation
│   │   └── validators.ts        # Input validation
│   └── types/
│       ├── index.ts             # TypeScript types
│       └── errors.ts            # Error types
├── tests/
│   ├── unit/                    # Unit tests
│   └── integration/             # Integration tests
├── config/
│   └── prompts/                 # Prompt templates
├── logs/                        # Log files
├── .env.example                 # Environment template
├── package.json
├── tsconfig.json
└── README.md

---

💻 Built-in Commands

Command	Alias	Description
help	h, ?	Show available commands
clear	cls, c	Clear terminal
exit	quit, q	Exit The Joker
history	hist	Show command history
status	stat	Check LM Studio connection
banner		Show welcome banner
version	ver, v	Show version info
agent		Run a query through the agent
memory	mem	Show agent memory stats
agent-status		Show agent state
reset-agent		Reset agent state

---

🔧 Available Tools

web_search

Search the web for information.

Parameters:
  - query: string (required) - Search query
  - numResults: number (default: 10) - Number of results
  - engine: string (default: 'google') - Search engine

scrape_page

Scrape content from a web page.

Parameters:
  - url: string (required) - URL to scrape
  - selectors: object (optional) - CSS selectors for extraction
  - waitFor: string (optional) - Wait for element
  - scroll: boolean (default: true) - Scroll to load content

extract_links

Extract all links from a page.

Parameters:
  - url: string (required) - URL to extract from
  - filter: string (optional) - Domain filter

process_data

Process and structure scraped data.

Parameters:
  - data: any (required) - Data to process
  - operation: string (required) - Operation type
  - options: object (optional) - Processing options

---

👨‍💻 Development

Development Mode

# Run in development mode with hot reload
npm run dev

# Build in watch mode
npm run build:watch

Scripts

Script	Description
npm start	Run the compiled application
npm run dev	Run with ts-node
npm run build	Compile TypeScript
npm run build:watch	Compile with watch mode
npm test	Run all tests
npm run test:watch	Run tests in watch mode
npm run test:coverage	Run tests with coverage
npm run lint	Run ESLint
npm run lint:fix	Fix ESLint issues
npm run format	Format with Prettier
npm run clean	Remove dist and logs

---

🧪 Testing

Running Tests

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific test file
npm test -- --testPathPatterns="parser"

# Run tests in watch mode
npm run test:watch

Test Coverage

The project maintains comprehensive test coverage:

Test 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	966	✅ All Passing

---

🤝 Contributing

We welcome contributions! Please read our Contributing Guide first.

Quick Contributing Steps

1. Read the CONTRIBUTING.md for guidelines
2. Check open issues
3. Comment on an issue to get assigned
4. Make your changes following our coding standards
5. Submit a Pull Request

⚠️ Important: This project uses the TJCL License. By contributing, you agree to the license terms.

---

🔒 Security

Found a security vulnerability? Please read our Security Policy and report responsibly.

DO NOT create public issues for security vulnerabilities.

📧 Report to: ratnakirtiscr@gmail.com

---

📖 Documentation

For comprehensive documentation, see:

• DOCUMENTATION.md - Full API reference and guides
• CONTRIBUTING.md - Contribution guidelines
• SECURITY.md - Security policy
• LICENSE - License terms

---

📄 License

This project is licensed under The Joker Contribution License (TJCL) v1.0.

Permission	Status
View source code	✅ Allowed
Contribute (Pull Requests)	✅ Allowed
Personal non-commercial use	✅ Allowed
Clone/Fork repository	❌ Not Allowed
Redistribute	❌ Not Allowed
Commercial use	❌ Not Allowed

See the LICENSE file for details.

---

🙏 Acknowledgments

Open Source Libraries

This project is built with these amazing open source libraries:

Library	Purpose	License
Puppeteer	Browser automation	Apache-2.0
puppeteer-extra	Plugin system	MIT
puppeteer-extra-plugin-stealth	Stealth mode	MIT
Axios	HTTP client	MIT
Cheerio	HTML parsing	MIT
Chalk	Terminal styling	MIT
Winston	Logging	MIT
Jest	Testing	MIT
TypeScript	Type safety	Apache-2.0

Special Thanks

• LM Studio for local LLM inference
• The open source community for their amazing tools and libraries

---

👤 Author

Ratna Kirti

---

Made with ❤️ by Ratna Kirti

🃏 The Joker - Agentic Terminal v1.0.0