How to Request a New Feature for GhostTrack: A Developer's Guide

To request a new feature for GhostTrack, open a GitHub issue using the "Feature request" template, describe your specific use-case, and reference the target architecture in GhostTR.py (such as adding a function decorated with @is_option and registering it in the menu list at lines 80-107).

GhostTrack is a single-file Python console application maintained in the HunxByts/GhostTrack repository that provides IP, phone number, and username tracking utilities through an interactive menu interface. Because the entire application lives in GhostTR.py with a deliberately flat architecture, requesting and implementing new tracking features follows a straightforward, predictable workflow. This guide explains exactly how to propose new functionality, where to modify the source code, and what technical details to include for rapid maintainer approval.

Understanding GhostTrack's Architecture

Before submitting a feature request, it helps to understand how GhostTrack organizes its codebase. The application is intentionally structured as a single script without complex module hierarchies, making it accessible for contributors.

Core Components in GhostTR.py

The main file GhostTR.py contains four distinct architectural layers that you will reference in your proposal:

• Menu definition (lines 80-107): A list of dictionaries mapping numeric choices to descriptions and callable functions, driving the interactive UI
• Option functions (defined from line 39 onward): Business logic implementations such as IP_Track, phoneGW, TrackLu, and showIP that contain the actual tracking logic
• Utility helpers (lines 29-78 and 190-259): UI scaffolding including the is_option decorator, clear(), run_banner(), call_option(), and execute_option() functions
• Entry point (lines 96-107): The main() loop that displays the banner, prints the menu, reads user input, and dispatches choices to the appropriate handler

How to Submit a Feature Request

The maintainers prefer the standard GitHub workflow for feature proposals. Following these steps increases the likelihood of acceptance:

1. Open an issue using the "New Issue" button on the HunxByts/GhostTrack repository
2. Select the "Feature request" template or use a clear, descriptive title such as "Add Email Tracker" or "Domain Lookup Feature"
3. Provide a concise description including the specific use-case and a high-level design sketch that references existing architecture (for example: "Add function email_lookup() using the @is_option decorator and register it with {'num': 5, 'text': 'Email Tracker', 'func': email_lookup} in the options list")
4. Tag with enhancement and link to a draft pull request if you have already implemented the feature

When describing your feature, reference exact line numbers where modifications would occur. For example: "Insert the new entry after the Phone Number Tracker block (lines 93-98 in GhostTR.py)."

Implementing a New Tracker

If you want to implement the feature yourself rather than just request it, GhostTrack's flat architecture makes extension simple. New features must follow the pattern established by existing trackers.

Step 1: Create the Tracker Function

Define your new function using the @is_option decorator and follow the color-coded output pattern used throughout the application:

@is_option
def email_tracker():
    email = input(f"\n {Wh}Enter email address {Gr}: {Wh}")
    # Example API integration (replace with actual endpoint)

    resp = requests.get(f"https://api.example.com/lookup?email={email}")
    data = resp.json()
    
    print(f"\n {Wh}========== {Gr}EMAIL INFORMATION{Wh} ==========")
    print(f"{Wh}Domain   :{Gr} {data.get('domain')}")
    print(f"{Wh}Breached :{Gr} {data.get('breached')}")
    # Add additional fields as needed

Step 2: Register the Menu Entry

Add a dictionary entry to the options list (located around lines 80-107 in GhostTR.py):

{
    'num': 5,
    'text': 'Email Tracker',
    'func': email_tracker
},

Ensure the num value is unique and sequential with existing options.

Step 3: Update Documentation

Optionally update the run_banner() function or README.md to reflect the new menu item. If you modify dependencies, update requirements.txt to include any new packages beyond the existing requests and phonenumbers.

Example: Proposing an Email Tracker

Here is a complete example of how to structure your feature request issue:

**Title:** Add Email Tracker

**Description**
I would like GhostTrack to resolve an email address to associated domain information and breach data.

**Motivation**
Security analysts often start investigations with an email address. Having a quick lookup inside GhostTrack would streamline the workflow without switching tools.

**Proposed Implementation**
1. Create function `email_tracker()` in `GhostTR.py` that:
   - Uses the `@is_option` decorator
   - Calls a public API (such as Hunter.io) using the existing `requests` dependency
   - Prints results using the `Wh` (White) and `Gr` (Green) color variables for consistency
2. Add menu entry after the Username Tracker block (lines 94-98):
   ```python
   {
       'num': 5,
       'text': 'Email Tracker',
       'func': email_tracker
   }

3. No new external dependencies are required beyond requests, which is already present in requirements.txt.

Additional Notes I can draft a pull request once the issue is approved and the API choice is confirmed.

## Summary

- GhostTrack uses a single-file architecture in [`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py) with a menu-driven interface defined at lines 80-107
- Feature requests should be submitted as GitHub issues tagged with `enhancement`, including specific references to the codebase architecture and line numbers
- New features require creating a function decorated with `@is_option` and registering it in the `options` list with `num`, `text`, and `func` keys
- The application maintains color-coded output patterns using variables like `Wh` and `Gr`, and relies only on `requests` and `phonenumbers` beyond the standard library
- Referencing specific implementation details (such as "insert after line 98") in your feature request accelerates maintainer review and approval

## Frequently Asked Questions

### Where is the main application code located?

All core functionality resides in [`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py) at the repository root. This single file contains the menu system (lines 80-107), tracker implementations (from line 39), and UI helpers (lines 29-78 and 190-259). The `main()` entry point runs the interactive loop at lines 96-107.

### Do I need to install additional dependencies to add a new feature?

GhostTrack intentionally minimizes dependencies, requiring only `requests` and `phonenumbers` beyond Python's standard library. If your feature absolutely requires additional packages, you must update [`requirements.txt`](https://github.com/HunxByts/GhostTrack/blob/main/requirements.txt) and explicitly justify the new dependency in your feature request to maintain the lightweight nature of the tool.

### How do I ensure my feature matches the existing code style?

Apply the `@is_option` decorator to your function definition, use the existing color variables (`Wh` for white prompts, `Gr` for green output) in your print statements, and implement graceful error handling with `try-except` blocks that follow the pattern seen in existing trackers like `IP_Track` and `phoneGW`.

### Can I submit a pull request without opening an issue first?

While the maintainers accept direct pull requests, opening an issue first allows discussion of feasibility, required API keys, rate limiting concerns, and licensing issues before you invest development time. Submitting a PR that follows the repository's coding style and references specific line numbers in [`GhostTR.py`](https://github.com/HunxByts/GhostTrack/blob/main/GhostTR.py) significantly improves the chances of rapid acceptance.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}