02. Architecture & Files

DevHunt leverages a lightweight stack, utilizing Flask (Python 3.10+) for the API server, SQLite for local persistence, and a Vite + React frontend for the modern IDE interface (compiled to a static bundle). The legacy plain HTML/JS frontend is also available as a fallback in the frontend/ directory.

Directory Structure Map

Understanding the exact locations of configuration files, engines, and persistence caches:

DevHunt/
├── backend/
│   ├── app.py                # Flask controller, static routing, SSE routes
│   ├── config.py             # Server paths (Uploads dir, DB files, and key files)
│   ├── check_requirements.py # Startup verification checks script
│   ├── core/
│   │   ├── document_analyzer.py # Multi-agent Document Forensics Orchestrator
│   │   ├── db.py                # Database connection pools & schema init
│   │   ├── key_manager.py       # API key health validation and rotation
│   │   ├── rag_pipeline.py      # RAG chunker, embedder, and vector database
│   │   ├── chat_engine.py       # SSE message streamer & chat session context
│   │   └── terminal_engine.py   # Command parse loops & OS process runners
│   └── uploads/              # Storage directory for ELA deltas & diagrams
├── frontend-src/          # Vite + React IDE (modern interface)
│   ├── src/                 # React components & pages
│   ├── dist/                # Compiled production bundle (served by Flask)
│   └── public/              # Static assets (docs.html, logs.html, logo.png)
├── frontend/              # Legacy plain HTML/JS interface (fallback)
├── run.bat                # Automated Windows launcher (port 1225)
├── run.sh                 # Automated macOS/Linux launcher
└── build_desktop.bat      # Full desktop EXE build script (Tauri + PyInstaller)

Database Persistence Schemas

The SQLite database file is stored at backend/data/devhunt.db. It serves as the primary persistent data warehouse for the platform. It manages the following tables:

1. Knowledge Sources Table (RAG Master)

Stores indexed documents, files, and URLs uploaded by the developer:

CREATE TABLE IF NOT EXISTS knowledge_sources (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT,
    type TEXT,           -- 'pdf', 'url', 'text', 'note', 'image'
    path TEXT,           -- Local absolute file location
    status TEXT,         -- 'indexed', 'pending', 'error'
    chunk_count INTEGER DEFAULT 0,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

2. Knowledge Chunks Table (RAG Vectors)

Stores raw text segments and their high-dimensional vector embeddings serialized as JSON arrays:

CREATE TABLE IF NOT EXISTS knowledge_chunks (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    source_id INTEGER,
    content TEXT,        -- Extracted chunk text
    embedding TEXT,      -- JSON-serialized float array
    metadata TEXT,       -- JSON-serialized page/position data
    FOREIGN KEY(source_id) REFERENCES knowledge_sources(id) ON DELETE CASCADE
);

3. Document Analyses Table (Forensics Results)

Caches weighted verification checklist results, verdicts, and file locations for generated Matplotlib charts:

CREATE TABLE IF NOT EXISTS document_analyses (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    source_id INTEGER UNIQUE,
    final_score REAL,
    verdict TEXT,
    risk_level TEXT,     -- 'LOW', 'MEDIUM', 'HIGH'
    report_json TEXT,    -- AI detailed local structured entity report
    ela_image_path TEXT,
    dashboard_image_path TEXT,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY(source_id) REFERENCES knowledge_sources(id) ON DELETE CASCADE
);

4. Chat Messages Table (History Tracker)

Maintains persistent conversational log history for standard assistant chats and document-specific forensics chats:

CREATE TABLE IF NOT EXISTS messages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    session_id TEXT,     -- 'default_session' or 'session_doc_<source_id>'
    role TEXT,           -- 'user' or 'assistant'
    content TEXT,
    model_used TEXT,
    key_used TEXT,       -- Key manager index label
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP,
    tokens_used INTEGER DEFAULT 0
);

5. Quests Table (Quest Board)

Tracks backlog items, priority values, and lifecycle milestones:

CREATE TABLE IF NOT EXISTS todos (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    description TEXT,
    priority TEXT,       -- 'high', 'medium', 'low'
    status TEXT,         -- 'pending', 'in_progress', 'done'
    due_date TEXT,
    tags TEXT,           -- JSON array of strings
    source TEXT,         -- 'manual' or 'ai_detected'
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    completed_at DATETIME
);

6. Analytics Events Table (Behavior Monitor)

Logs developer actions and triggers for path auto-adjusting logic:

CREATE TABLE IF NOT EXISTS analytics_events (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    event_type TEXT,     -- 'question_asked', 'todo_completed', 'path_updated'
    topic TEXT,
    metadata TEXT,       -- JSON event context details
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP
);

7. System Logs Table (Logs Console)

Stores detailed system operations accessible in the Log Console `/logs` panel:

CREATE TABLE IF NOT EXISTS system_logs (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    level TEXT,          -- 'INFO', 'WARN', 'ERROR', 'SUCCESS'
    category TEXT,       -- 'api_call', 'key_event', 'chat', 'rag', 'system'
    message TEXT,
    metadata TEXT,       -- JSON payload (e.g. response duration)
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP
);

8. User Memories Table (AI Facts)

Stores long-term facts extracted from conversations during periodic consolidations:

CREATE TABLE IF NOT EXISTS user_memories (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    session_id TEXT UNIQUE,
    consolidated_facts TEXT, -- JSON-serialized string array
    last_updated DATETIME DEFAULT CURRENT_TIMESTAMP
);

9. LinkedIn Drafts Table

Stores LinkedIn post drafts created via the Drafts panel or auto-saved from the AI chat interface:

CREATE TABLE IF NOT EXISTS linkedin_drafts (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,
    content TEXT NOT NULL,
    status TEXT DEFAULT 'draft',  -- 'draft' or 'ready'
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Config Files & Filesystem Paths

Key configuration files are kept in the backend/data/ directory:

• Database Storage (backend/data/devhunt.db): Stores the SQLite tables listed above.
• Key Configuration (backend/data/keys.json): Stores API keys registered via CLI or GUI. API keys are stored encrypted locally.
• User Profile (backend/data/profile.json): Stores developer name, streak milestone metrics, current/target skill sets, daily study target times, and interface parameters.
• Settings file (backend/data/settings.json): Stores default system parameters (e.g. selected LLM overrides, themes).
• Learning Path Tracker (backend/data/learning_path.json): Stores the dynamically structured learning tracks, streak counts, progress nodes, and completion states.
• Encryption Secret (backend/data/.secret): Automatically generated key file containing the Fernet encryption secret used to encrypt registered API keys.
• Uploads Repository (backend/uploads/): Directory used to save raw document files, generated Matplotlib dial graphs, and ELA contrast heatmaps.

03. Setup & Installation

This manual covers how to install, verify, and run the DevHunt application suite. The platform offers compiled native installers for Windows, and automated shell bootstrap scripts for macOS, Linux, and Windows source configurations.

Prerequisites (Running from Source)

• Python Version: Python >= 3.10 is required on the host system.
• System Path: Python and pip must be configured in your environment variable PATH.
• Tesseract OCR: (Optional) Install Tesseract-OCR to enable rule-based local backup text parsing.

1. Precompiled Installers (Windows Desktop)

For a native desktop experience on Windows 10 or 11, use the precompiled installers. These bundle both the frontend shell (Tauri) and python core (PyInstaller) together:

• Standard Setup (EXE): Double-click DevHunt_Setup.exe to launch the installation wizard. It installs DevHunt into your local profile directory and registers desktop/start menu shortcuts automatically.
• Enterprise Installer (MSI): Run DevHunt_Setup.msi for system-wide administrative deployments.

2. Shell Automation Launcher (macOS & Linux)

On Unix-based operating systems, use the automated bootstrap script to compile the workspace environment and start the application:

# Make script executable (if needed)
chmod +x run.sh

# Run launcher
./run.sh

The launcher automatically checks the system Python version, initializes a virtual environment (backend/venv/), installs dependencies from `requirements.txt`, sets up local loopback auth tokens, and opens your default browser at `http://localhost:1225`.

3. CLI Launcher (Windows from Source)

If running from source on Windows, execute the command batch file in the root folder:

run.bat

This script replicates the shell verification checks, sets up the local Python virtual environment, and boots the Flask API server side-by-side with Vite compilation.

4. Container Deployment (Docker)

5. Startup Verification Checks

To verify that all local computer vision, file analysis, and database libraries are correctly imported inside your virtual environment, run the requirement verifier:

# Activate virtual env first, then run:
python check_requirements.py

04. Troubleshooting Guide

Common installation anomalies and developer instructions on how to bypass them immediately:

Database Lock Resolution

Stop-Process -Name "python" -Force

Port 1225 Address Busy

netstat -ano | findstr 1225
# Kill process using the PID found at the end of output line
taskkill /PID <PID> /F

Pyzbar DLL Loading Mismatches

05. REST API Specification

DevHunt exposes standard REST endpoints alongside stream interfaces. All parameters, JSON schemas, and streaming SSE responses are detailed below.

1. Document Forensics Endpoints

Analyze Document Check

POST /api/knowledge/<source_id>/analyze

Executes VerifierAgent, AnalystAgent, and ReporterAgent processes, caching details into `document_analyses` table.

// Response (200 OK)
{
  "success": true,
  "source_id": 16,
  "score": 72.8,
  "verdict": "⚠️ Suspicious (Review Recommended)",
  "risk_level": "MEDIUM",
  "ela_image": "receipt.pdf_ela.png",
  "dashboard_image": "receipt.pdf_dashboard.png"
}

Get Analysis Report

GET /api/knowledge/<source_id>/analysis

Fetches cached analysis checks results details.

// Response (200 OK)
{
  "success": true,
  "analyzed": true,
  "score": 72.8,
  "verdict": "⚠️ Suspicious (Review Recommended)",
  "risk_level": "MEDIUM",
  "ela_image_path": "receipt.pdf_ela.png",
  "dashboard_image_path": "receipt.pdf_dashboard.png",
  "report_json": { ... }
}

2. Chat & SSE Stream Specification

JSON Chat Query

POST /api/chat

Submit questions about an indexed document. Include source_id to fetch document RAG blocks.

// Request payload
{
  "message": "What is the PNR code of this travel ticket?",
  "session_id": "session_doc_16",
  "source_id": 16
}

Server-Sent Events (SSE) Stream

POST /api/chat/stream

Submits a message and establishes a connection header text/event-stream to stream response tokens:

data: {"text": "The"}
data: {"text": " PNR"}
data: {"text": " code"}
data: {"text": " is..."}

3. Chat History Endpoints

Fetch Session Chat Logs

GET /api/chat/history?session_id=<session_id>

Retrieves all message blocks associated with the active session identifier. Standard chats use default_session, whereas forensics document chats use the format session_doc_<source_id>.

// Response (200 OK)
{
  "success": true,
  "history": [
    {"role": "user", "content": "What is ELA?", "timestamp": "..."},
    {"role": "assistant", "content": "Error Level Analysis resaves...", "timestamp": "..."}
  ]
}

Delete Session Chat Logs

DELETE /api/chat/history?session_id=<session_id>

Clears chat logs associated with the session.

// Response (200 OK)
{
  "success": true,
  "message": "History cleared"
}

4. Quest Board (Todos) Endpoints

List Active Quests

GET /api/todos?status=<filter>&priority=<filter>

Lists todos in the SQLite database.

// Response (200 OK)
{
  "success": true,
  "todos": [
    {"id": 4, "title": "Configure SSL", "priority": "high", "status": "pending"}
  ]
}

Create New Quest

POST /api/todos

Adds a new quest item.

// Request payload
{
  "title": "Configure local virtual environment",
  "description": "Install libraries inside venv",
  "priority": "medium",
  "due_date": "2026-06-20",
  "tags": ["setup", "env"]
}

Update / Modify Quest Details

PUT /api/todos/<todo_id>

Updates priority, description, title, or status details.

Mark Quest Complete

POST /api/todos/<todo_id>/complete

Marks quest completed and logs timestamp.

Delete Quest Entry

DELETE /api/todos/<todo_id>

Removes quest item completely.

5. Learning Path Endpoints

Get Curriculum Map

GET /api/path

Fetches the learning tracks structure from learning_path.json.

Generate Dynamic Path

POST /api/path/generate

Dynamically compiles path modules based on user profiles skill settings.

Update Progression Node

PUT /api/path/update

Modifies study day status (e.g. {"day": 2, "status": "completed"}).

Fetch Today's Study Target

GET /api/path/today

Returns daily goals and active checkpoints.

6. Intel Vault (Knowledge Base) Endpoints

List Vault Sources

GET /api/knowledge

Lists metadata for all uploaded documents.

Upload File to Vault

POST /api/knowledge/upload

Uploads PDF, TXT, MD, or Image files. Automatically triggers asynchronous RAG background sync chunking.

Index URL Web Content

POST /api/knowledge/url

Extracts web content from a URL, index as RAG vectors.

Save Note to Vault

POST /api/knowledge/note

Indexes custom title and text content nodes directly.

Delete Vault Source

DELETE /api/knowledge/<source_id>

Removes RAG chunks and master sources entries.

Retrieve Source Content

GET /api/knowledge/<source_id>/content

Returns full text contents compiled from raw knowledge chunks.

7. LinkedIn Drafts Endpoints

Full CRUD interface for managing LinkedIn post drafts. Drafts can be created, updated, refined with AI, or deleted. All data is stored locally in SQLite.

List All Drafts

GET /api/linkedin/drafts

Returns all drafts sorted by created date (newest first).

Create Draft

POST /api/linkedin/drafts

// Request: { "title": "...", "content": "..." }
// Response: { "success": true, "id": 42 }

Update Draft

PUT /api/linkedin/drafts/<id>

// Request: { "title": "...", "content": "...", "status": "ready" }
// Response: { "success": true }

Delete Draft

DELETE /api/linkedin/drafts/<id>

Refine Draft with AI

POST /api/linkedin/drafts/<id>/refine

Passes existing draft content through the AI model with a LinkedIn optimization prompt.

// Response: { "success": true, "refined": "Polished post content..." }

06. Forensics Agents Checklist

During the document analyze execution, the orchestrator triggers VerifierAgent which runs a weighted 5-layer checklist check on the uploaded file:

Visual Dashboard Rendering

Upon analysis completion, ReporterAgent compiles the weighted checklists scores and saves a premium vertically-stacked Matplotlib dashboard image (dimensions: 6.5x7.5 inches) containing:

1. An **Authenticity Dial** (half-arc gauge) mapping the combined score from green (authentic) to red (tampering detected).
2. A **Horizontal Bar Graph** displaying individual layer scores on a normalized percentage base.

07. Rule-Based Engine (Quota Safety)

Free-tier Gemini API connections are subject to strict rate limits (20 requests per day), which will trigger **429 RESOURCE_EXHAUSTED** errors when scanning multiple files or testing pipelines.

Local Rule-Based Scans

To ensure reliability, the document analyze step bypasses Gemini API calls entirely. AnalystAgent uses a fast local heuristics engine to populate fields:

• Text Snippet Summary: Compiles summaries detailing character size and file format details.
• Entity Extractor: Regex-based parses that pull dates, amounts, e-mails, phone numbers, Aadhaar IDs, and PANs locally.
• Authenticity View: Resolves risk assessments based on VerifierAgent scores (Risk Levels: LOW, MEDIUM, or HIGH).
• Zero Latency: Cuts scan times in half (from 17.20 seconds down to 8.93 seconds).

Preserved Chat Capabilities

Gemini API usage is preserved exclusively for interactive document chat sessions. Chat queries use indexed RAG blocks to answer questions while scanning remains rate-limit free.

08. Hunt Terminal (CLI)

The Hunt Terminal is an interactive console that processes system shell scripts and custom commands. Each command is detailed below:

In-Depth Command Index

Each terminal command is mapped below with its specific flags, operational behavior, parameters, and example output formats.

◎ 01. hunt help

Syntax: hunt help [command]

Lists all available terminal commands. If a command name is provided as an argument, it pulls specific usage text and available flags from the command-level help mapper.

$ hunt help ls
Usage: hunt ls [options] [path]

Lists directory contents in a cross-platform format.

Options:
  -a          Show hidden files (filenames starting with '.')
  -l          Display detailed listing (type, size, last modified)

◎ 02. hunt neofetch

Syntax: hunt neofetch

Displays system details about the active DevHunt server node. It compiles Host OS details, kernel version, shell runtime, active CPU core metrics, memory usage, and active workspace paths, side-by-side with a premium ASCII logo.

$ hunt neofetch
      /\_/\      guest@devhunt
     ( o.o )     -------------------
      > ^ <      OS: Windows 10 (AMD64)
    /  | |  \    Kernel: 10.0.19045 Build 19045
   (  |_|_|  )   Shell: Hunt Terminal v1.0
    \_______/    CPU: AMD Ryzen 5 (12 Cores)
   DEVHUNT NODE  Memory: 8192MB / 16384MB (50%)
                 Workspace Path: e:\git-projects\DevHunt

◎ 03. hunt pwd

Syntax: hunt pwd

Prints the current absolute directory path where the terminal session is operating. Used to check context state before executing relative file paths.

$ hunt pwd
e:\git-projects\DevHunt

◎ 04. hunt ls

Syntax: hunt ls [options] [path]

Lists contents of the active directory in a clean, colored format (directories in cyan, executables/scripts in green). If path is supplied, scans the target path.

Options:

• -a : Include hidden files starting with a dot (e.g. .gitignore).
• -l : Long list format displaying permissions, file sizes, last modified times, and names.

$ hunt ls -l
-rw-r--r--  1 guest staff     1048 Jun 13 11:17 config.py
drwxr-xr-x  1 guest staff        - Jun 13 11:17 core/
-rwxr-xr-x  1 guest staff     5514 Jun 13 11:17 run.bat*

◎ 05. hunt cd

Syntax: hunt cd [path]

Changes the working directory of the terminal session. If executed without arguments, returns to the project workspace root. It warns the user if they navigate outside the DevHunt workspace boundaries.

$ hunt cd backend
Switched session context to e:\git-projects\DevHunt\backend

◎ 06. hunt cat

Syntax: hunt cat <filename>

Reads and displays the text contents of a file in the terminal. The output is bounded at 5,000 characters to prevent crashing browser page rendering.

$ hunt cat config.py
import os
UPLOADS_DIR = "uploads"
KEYS_PATH = "data/keys.json"

◎ 07. hunt mkdir

Syntax: hunt mkdir <directory_name>

Creates a new directory folder at the specified target path. Creates intermediate directories automatically if they do not exist.

$ hunt mkdir temp_data
Directory successfully created: temp_data

◎ 08. hunt rm

Syntax: hunt rm [options] <path>

Deletes a file or directory. Directory deletion requires the recursive option flag.

Options:

• -r : Recursive deletion. Required to delete directories and their sub-contents.

$ hunt rm -r temp_data
Successfully deleted directory tree: temp_data

◎ 09. hunt myip

Syntax: hunt myip

Performs an external network check to retrieve the server's public IP address, ISP provider name, ASN, routing city, country, coordinates, and local timezone offset.

$ hunt myip
NODE NETWORK COORDINATES:
  Public IP Address : 203.0.113.50
  ISP/Provider      : Reliance Jio Infocomm (AS55836)
  Location          : Mumbai, Maharashtra, India
  Coordinates       : Lat: 19.076, Lon: 72.8777
  Timezone          : Asia/Kolkata (Offset: +05:30)

◎ 10. hunt ping

Syntax: hunt ping <host> [options]

Checks network latency to a remote server. Because standard ICMP packets require administrative root access, this command performs TCP handshake timing checks against target ports.

Options:

• -c <count> : Number of handshake tests to run (default: 4).
• -p <port> : Target TCP port to connect to (default: 80).

$ hunt ping google.com -c 3
HUNT PING google.com (142.250.190.46) using port 80/TCP:
Testing 3 handshakes...
  Connection from 142.250.190.46: seq=1 time=24.15 ms status=CONNECTED
  Connection from 142.250.190.46: seq=2 time=22.80 ms status=CONNECTED
  Connection from 142.250.190.46: seq=3 time=23.45 ms status=CONNECTED

--- google.com ping statistics ---
  3 packets transmitted, 3 received, 0.0% packet loss
  rtt min/avg/max = 22.80/23.47/24.15 ms

◎ 11. hunt dns (and hunt dig)

Syntax: hunt dns <domain> [record_type]

Queries DNS records for a domain using Google's secure DNS-over-HTTPS API. Displays records, TTL values, and response IP metadata.

Record Types: A, AAAA, MX, TXT, NS, CNAME (default is A).

$ hunt dns github.com MX
DNS lookup for github.com (Record Type: MX)
Resolving via secure DNS-over-HTTPS...
TYPE   TTL      DATA
--------------------------------------------------
MX     3600     10 mxb-01.play.spf.protonmail.ch.
MX     3600     20 mxb-02.play.spf.protonmail.ch.

◎ 12. hunt whois

Syntax: hunt whois <domain>

Queries public registrar databases to find registration ownership details, name servers, creation dates, and expiration intervals.

$ hunt whois google.com
WHOIS Query for 'google.com' via port 43 socket connection:
Connecting to whois.iana.org...
Redirecting query to registry server: 'whois.verisign-grs.com'...

DOMAIN SUMMARY:
  Domain Name       : google.com
  Registrar         : MarkMonitor Inc.
  Created On        : 1997-09-15T04:00:00Z
  Expires On        : 2028-09-14T04:00:00Z
  Name Servers      : ns1.google.com, ns2.google.com

◎ 13. hunt headers

Syntax: hunt headers <url>

Fetches HTTP response headers from a web address and verifies critical security settings such as Content Security Policy (CSP), HSTS, and Frame protections.

$ hunt headers google.com
Checking headers for https://google.com...
Response received in 120.45 ms with Status Code: 200

HTTP HEADERS:
  content-type: text/html; charset=ISO-8859-1
  cache-control: private, max-age=0
  x-frame-options: SAMEORIGIN
  x-xss-protection: 0

◎ 14. hunt ssl

Syntax: hunt ssl <host>

Establishes a TLS connection to check a domain's SSL/TLS certificate chain. It audits the certificate's issuer, cryptographic strength, common name validity, and expiration details.

$ hunt ssl google.com
SSL Certificate Audit for google.com:
  Common Name  : *.google.com
  Issuer       : Google Trust Services LLC
  Validity     : Valid (Expires in 58 days)
  Algorithm    : sha256WithRSAEncryption

◎ 15. hunt port

Syntax: hunt port <host> <port>

Checks if a specific TCP port is open and listening on a target host. Uses socket connection timeouts to assess port connectivity quickly.

$ hunt port localhost 1225
Port 1225 is OPEN on localhost

◎ 16. hunt trace

Syntax: hunt trace <host>

Simulates a network traceroute path to a target host, checking hop latency and attempting to resolve geolocations for each gateway node.

$ hunt trace 8.8.8.8
Tracing route to 8.8.8.8 (dns.google):
  Hop 1: 192.168.1.1 (1.24 ms)
  Hop 2: 10.0.0.1 (10.50 ms)
  Hop 3: 8.8.8.8 (22.10 ms) [Target Reached]

◎ 17. hunt subdomains

Syntax: hunt subdomains <domain>

Scans for active subdomains of a target domain passively by resolving common DNS host prefixes (e.g. mail, api, dev, blog) against the domain.

$ hunt subdomains github.com
Scanning subdomains for github.com...
  Found: api.github.com
  Found: pages.github.com
  Found: status.github.com

◎ 18. hunt git

Syntax: hunt git <arguments>

A wrapper command that runs native git commands securely in the current workspace. Allows tracking modifications, staging changes, or checking logs without leaving the console.

$ hunt git status
On branch main
Your branch is up to date with 'origin/main'.

Changes not staged for commit:
  modified:   frontend/docs.html

◎ 19. hunt python

Syntax: hunt python -c "<code>"

Runs a single Python command line statement within the active virtual environment context. Returns standard output or syntax errors immediately.

$ hunt python -c "import sys; print(sys.version)"
3.10.11 (tags/v3.10.11:7d4061c, May 17 2023, 20:06:55)

◎ 20. hunt calc

Syntax: hunt calc <expression>

Evaluates math expressions safely without allowing execution injection vectors. It supports trigonometric functions, logarithms, roots, and standard arithmetic operations.

$ hunt calc "sqrt(144) * log2(256)"
Result: 96.00

◎ 21. hunt localports

Syntax: hunt localports [options]

Lists active network sockets, listening ports, and connection states on the localhost machine. Helps diagnose port occupancy conflicts.

Options:

• -a : Show all connections (including established active sockets).
• -l : Show listening sockets only (default behaviour).

$ hunt localports
ACTIVE LOCAL LISTENERS:
  Proto  Local Address          State
  TCP    127.0.0.1:1225         LISTENING
  TCP    127.0.0.1:27017        LISTENING

◎ 22. hunt portscan

Syntax: hunt portscan <host> [options]

Scans TCP ports on a host to identify active listening services. Scans are run in parallel to minimize wait times.

Options:

• -r <range> : Specific port ranges (e.g. 20-100) or search profiles (e.g. common to test ports 21, 22, 23, 25, 53, 80, 443, 8080).
• -t <timeout> : Socket timeout duration in seconds per port connection (default: 0.5s).

$ hunt portscan localhost -r common
Scanning common ports on localhost...
  Port 80/TCP   : CLOSED
  Port 443/TCP  : CLOSED
  Port 1225/TCP : OPEN (Flask server)

◎ 23. hunt quest

Syntax: hunt quest [add <title> [priority] [desc] | done <id> | rm <id>]

Provides command-line management for the SQLite-backed Quest Board. Running the command without arguments lists all active quest items in a tabular format.

$ hunt quest add "Complete Docs" high "Write detailed feature walkthroughs"
Quest successfully added! ID: 12

$ hunt quest
ID  TITLE            PRIORITY  STATUS
------------------------------------------
12  Complete Docs    high      backlog
08  Database fix     medium    in_progress

◎ 24. hunt keys

Syntax: hunt keys [list | add <key> [label] | rm <id> | test <id>]

Interacts with the Key Manager to register, audit, test, or delete Gemini API keys. Displays rate-limit metrics and cooldown trackers.

$ hunt keys list
ID   KEY PREFIX  LABEL         STATUS    REQUESTS (24H)
-------------------------------------------------------
1    AIzaSyB...  Gemini Key 1  Active    14 / 20
2    AIzaSyD...  Gemini Key 2  Active    0 / 20

◎ 25. hunt memory

Syntax: hunt memory [refine | clear]

Lists, refines, or clears long-term cognitive developer facts cached by the AI assistant during chat interactions.

$ hunt memory
AI CONSOLIDATED DEVELOPER MEMORIES:
  - User prefers dark mode.
  - Python project uses Flask backend at port 1225.

◎ 26. hunt backup

Syntax: hunt backup export

Exports all SQLite tables (quests, key statuses, chat history metadata) and local config JSON files into a consolidated backup directory structure.

$ hunt backup export
Backing up DevHunt Database...
Backing up Configuration profiles...
Backup file successfully created: backend/data/backup_20260613.json

◎ 27. hunt history

Syntax: hunt history [limit]

Retrieves the message logs of the active chat session from the database, helping developers debug recent prompts and token flows.

$ hunt history 2
[2026-06-13 11:15] User: How is ELA computed?
[2026-06-13 11:15] AI: ELA resaves image blocks at 75% quality...

◎ 28. hunt notifications

Syntax: hunt notifications [list | read [all | <id>] | detail <id>]

Lists, displays, or marks notifications and system log messages. Helps monitor background scanner alerts or database locks.

$ hunt notifications list
ID   SEVERITY  MESSAGE                              READ
--------------------------------------------------------
1    WARNING   Gemini API Key 1 hit quota 429 limit  No
2    SUCCESS   Database schema check completed       Yes

◎ 29. hunt stats

Syntax: hunt stats

Aggregates conversation messages from the SQLite database to analyze approximate token counts, key workloads, and model choices.

$ hunt stats
DEVHUNT TOKEN & API METRICS ANALYSIS
==================================================
  Total Conversations Logged : 32 exchanges
  Total Approximate Tokens   : 14502 tokens

MODEL USAGE DISTRIBUTION:
  MODEL NAME                | REQUESTS   | EST. TOKENS 
  -----------------------------------------------------
  gemini-3.1-flash-lite     | 24         | 8940        
  gemini-2.5-flash          | 8          | 5562        

API KEY WORKLOAD ANALYSIS:
  KEY LABEL / MASKED        | REQUESTS   | EST. TOKENS 
  -----------------------------------------------------
  Primary Gemini Key        | 30         | 13802       
  Backup Key 2              | 2          | 700         

* Token approximations are estimated as character length divided by 4.

Host CLI Terminal Launcher

DevHunt provides native launcher scripts (hunter.bat for Windows and hunter for Unix/macOS) to interface with the DevHunt CLI engine directly from your system shell.

Usage:

Run the launcher script with the -dt (direct terminal) flag from your command line to launch an interactive container shell context on your host system:

$ hunter -dt
guest@devhunt:~$ 

09. Workspace IDE & Themes

The DevHunt Workspace IDE transforms the traditional RAG cognitive helper dashboard into a fully featured offline developer center. It introduces real-time file tree traversal, workspace document editing, custom line styling, and a multi-theme environment.

File Explorer Tree

The left side layout hosts a collapsible panel rendering directory listings dynamically from the local workspace. Built recursive traversal logic automatically filters out build, configuration, and environment files such as .git, node_modules, venv, and __pycache__. Clicking folders opens/closes sub-trees locally, and clicking individual files retrieves text contents for code auditing.

Integrated Workspace Editor

The main workspace tab hosts a charcoal-colored monospaced text editor pane featuring:

• Line Numbers Indicator: Scroll-synchronized layout tracking document heights.
• Keyboard Hook Tab Override: Pressing Tab inserts 4 space characters instead of shifting focus elements.
• Instant disk syncing: Save modifications instantly back to disk with the Save button or Ctrl+S keyboard shortcuts.
• Centered Window Title: A central title bar dynamically displays the open relative file path (e.g. frontend/app.js - DevHunt) or defaults to DevHunt when cleared.
• VS Code-Style Sidebar Toggling: Clicking an active Activity Bar icon toggles the File Explorer sidebar visibility; clicking another icon switches panels and expands the sidebar.
• Collapsible File Explorer Sidebar Visibility: The File Explorer sidebar is restricted to only show/open when the Code Editor panel is active. Switching to any other panel (AI Assistant, stats, settings, etc.) automatically collapses/hides the explorer sidebar to keep the workspace clean.
• Inline New File Creator: Avoids browser-level prompt() dialogues. Click the + button in the file explorer sidebar header or press Ctrl+N to render an inline text input box at the top of the tree. Type the filename and press Enter to save an empty file to disk via POST /api/ide/file, refresh the file tree explorer, and load it in the editor. Pressing Escape or blurring cancels.
• Keyboard Shortcut (⌘K / Ctrl+K): Instantly focuses the AI Assistant chat input (#chat-input).
• Collapsible Bottom Terminal Pane: Pressing the Terminal button in the editor header menu splits the main text editing workspace horizontally to display an integrated container shell CLI. This terminal panel maintains unified navigation context and command history.
• Default Workspace Protection (Isolation): Launches in a safe empty_workspace/ subdirectory by default to isolate project resources and prevent traversal until a specific local folder is explicitly loaded via the File menu or keyboard shortcuts.

Backend IDE REST API endpoints

Multi-Theme Control System & Accent Polishing

DevHunt implements dynamic theme modifications switching color variables under body tags:

• Industrial Slate (Default): Pervasive dark slate and charcoal tones, professional blue borders, and low-contrast labels to reduce eye fatigue.
• Cyberpunk Neon: Glowing accent rules, purple card outlines, cyan badges, and a custom canvas background particle thread.
• Minimalist Light (Polished): A clean, premium white/light-gray theme using a premium Indigo accent (#4f46e5) instead of cyan. All inputs, textareas, and selects feature a white background with dark charcoal text. User chat bubbles are solid Indigo with white text, and AI bubbles are clean light gray. Quest Kanban cards are set to solid white backgrounds for readability against columns.
• Theme-Aware Charts: The analytics canvases dynamically adapt to the Light theme. They check body.theme-light and paint grid lines, borders, labels, and text colors in dark, legible tones automatically.

To optimize performance, when the Slate or Light theme is active, the backend canvas animation thread is automatically bypassed, saving local CPU cycles. Theme selections automatically persist in SQLite database profiles and local cache arrays.

10. LinkedIn Post Drafts

The LinkedIn Post Drafts module is a native workspace panel that captures LinkedIn-oriented content generated during AI chat sessions and organizes it as a private draft notebook. It integrates AI detection with a full CRUD management interface for drafts.

How It Works

When you chat with the AI Assistant and ask it to create a LinkedIn post, the system automatically detects relevant content in the assistant's response. A Save to LinkedIn Drafts button appears directly on the AI message bubble, allowing you to one-click save the content without leaving the chat.

All saved drafts are stored persistently in the local SQLite database and are accessible via the LinkedIn Drafts tab in the left activity bar.

LinkedIn Drafts Panel

The LinkedIn Drafts panel features two views side-by-side:

• Draft List (Left): A chronological list of saved drafts with dates, titles, and status labels (Draft / Ready). Organized by date headers.
• Draft Detail (Right): A full read-and-edit view showing the post content, a character count indicator, refine options, and action buttons.

Draft Actions

• ✦ Refine with AI: Sends the draft content back to the AI Assistant with a LinkedIn-optimization prompt, generating improved text that can replace the original.
• Copy to Clipboard: One-click copy for pasting directly into LinkedIn's post editor.
• Mark as Ready: Toggles draft status from Draft → Ready to track which posts are approved for publishing.
• Delete Draft: Permanently removes a single draft entry.
• Add Draft Manually: Opens a new draft form in the panel for creating drafts from scratch without AI input.

AI Chat Auto-Detection

The detection logic works by scanning the AI assistant's response text for LinkedIn-related keywords, including:

• Trigger phrases: LinkedIn post, post on LinkedIn, LinkedIn draft, Here are some LinkedIn post options
• Structured sections: Content blocks starting with Option 1:, Post:, or similar LinkedIn post format headers

When a match is detected, a LinkedIn button is injected into the message bubble footer. Clicking it extracts the draft text and opens a save confirmation dialog showing a title field and the content preview.

API Endpoints

List All Drafts

GET /api/linkedin/drafts

Returns all LinkedIn drafts ordered by created date descending.

// Response (200 OK)
{
  "success": true,
  "drafts": [
    {
      "id": 1,
      "title": "Celebrating 1 Year at DevHunt",
      "content": "Excited to share...",
      "status": "draft",
      "created_at": "2026-06-14 10:30:00"
    }
  ]
}

Create a Draft

POST /api/linkedin/drafts

// Request body (JSON)
{ "title": "My Post Title", "content": "Full post text..." }

// Response (201 Created)
{ "success": true, "id": 42 }

Update a Draft

PUT /api/linkedin/drafts/<id>

// Request body (JSON)
{ "title": "Updated Title", "content": "Updated content...", "status": "ready" }

Delete a Draft

DELETE /api/linkedin/drafts/<id>

// Response
{ "success": true }

Refine a Draft

POST /api/linkedin/drafts/<id>/refine

Sends the draft content to the AI model with a LinkedIn optimization prompt. Returns refined post copy.

// Response (200 OK)
{
  "success": true,
  "refined": "✨ Polished LinkedIn post text here..."
}

Settings Toggle

The LinkedIn Drafts feature can be toggled from the Settings tab under Feature Access Toggles. Disabling it hides the LinkedIn Drafts tab from the activity bar and panel navigation. Enabling it restores the tab and reloads the drafts list automatically.

11. Contributing & Support

DevHunt is open-source. We welcome contributions to optimize the forensic engines and add more CLI tools.

GitHub Issue Tracker

If you encounter database lockups, rate limit errors, or missing DLLs, please create a ticket in our issue tracker:

Version Changelog

A chronological history of releases and security patches implemented in the DevHunt workspace: