Where Are Prospect Data, Proposals, and Reports Stored in Geo-SEO Claude?

All CRM-related data in the Geo-SEO Claude repository is stored in a hidden directory at ~/.geo-prospects/ within the user's home folder, separating persistent data from the application codebase.

The zubair-trabzada/geo-seo-claude project implements a file-based CRM system that keeps prospect records, SEO audits, generated proposals, and comparison reports outside the git repository. Understanding exactly where prospect data, proposals, and reports are stored is critical for data backup, migration, and troubleshooting workflows across the skill modules.

The ~/.geo-prospects/ Directory Structure

The application centralizes all data persistence under a single root path constructed via Python's pathlib module. According to scripts/webapp/app.py, the base directory is defined as Path.home() / ".geo-prospects", which resolves to ~/.geo-prospects/ on Unix systems and the equivalent hidden folder on Windows.

This architecture maintains repository cleanliness while ensuring data survives between CLI sessions and web application restarts. The directory contains four distinct storage areas: the master JSON database, audit outputs, proposal documents, and monthly comparison reports.

Specific Storage Locations by Data Type

Prospect Database (prospects.json)

The master prospect registry resides at ~/.geo-prospects/prospects.json. In scripts/webapp/app.py, the code explicitly defines this location as:

CRM_PATH = Path.home() / ".geo-prospects" / "prospects.json"

This file contains a JSON array of prospect dictionaries and serves as the single source of truth for the web interface. When the application loads, it calls load_prospects() to parse this file into memory.

SEO Audit Output Files

Raw technical SEO audits are written to ~/.geo-prospects/audits/<domain>-<date>.md. As documented in skills/geo-prospect/SKILL.md, each audit command generates a timestamped Markdown file containing the raw crawl data and technical findings for a specific domain before proposal generation occurs.

Generated Proposals

Proposal documents are stored in ~/.geo-prospects/proposals/<domain>-proposal-<date>.md. The skills/geo-proposal/SKILL.md file specifies that the proposal generation command creates uniquely named Markdown files combining the target domain and generation date, allowing version history without database complexity.

Monthly Comparison Reports

Month-over-month SEO tracking reports live at ~/.geo-prospects/reports/<domain>-monthly-<YYYY-MM>.md. Per skills/geo-compare/SKILL.md, the compare command outputs dated Markdown files using a YYYY-MM format to facilitate historical performance analysis.

Code Implementation and Path Construction

The filesystem abstraction is implemented in scripts/webapp/app.py using pathlib.Path objects for cross-platform compatibility. Here are the specific patterns used to reference where prospect data, proposals, and reports are stored:

# Load all prospects (used by the web UI)

from pathlib import Path
import json

CRM_PATH = Path.home() / ".geo-prospects" / "prospects.json"

def load_prospects() -> list[dict]:
    if not CRM_PATH.is_file():
        return []
    with CRM_PATH.open(encoding="utf-8") as f:
        return json.load(f)

# Build the path for a new proposal file

from datetime import date
from pathlib import Path

PROPOSALS_DIR = Path.home() / ".geo-prospects" / "proposals"

def proposal_path(domain: str) -> Path:
    today = date.today().isoformat()
    filename = f"{domain}-proposal-{today}.md"
    return PROPOSALS_DIR / filename

# Example: storing a monthly report

from datetime import datetime
from pathlib import Path

REPORTS_DIR = Path.home() / ".geo-prospects" / "reports"

def report_path(domain: str, month: str) -> Path:
    # month format: "2026-03"

    filename = f"{domain}-monthly-{month}.md"
    return REPORTS_DIR / filename

Automatic Directory Initialization

The system creates the required hierarchy automatically the first time a command executes. The application uses mkdir -p equivalents (via Path.mkdir(parents=True, exist_ok=True)) to ensure ~/.geo-prospects/audits, ~/.geo-prospects/proposals, and ~/.geo-prospects/reports exist before writing files. This eliminates setup requirements while maintaining the hidden directory structure.

Summary

• Primary storage root: ~/.geo-prospects/ in the user's home directory, as defined in scripts/webapp/app.py
• Prospect database: prospects.json stored in the root of the .geo-prospects folder
• Audit files: Markdown files in ~/.geo-prospects/audits/ with <domain>-<date>.md naming convention
• Proposals: Markdown files in ~/.geo-prospects/proposals/ using <domain>-proposal-<date>.md format
• Reports: Markdown files in ~/.geo-prospects/reports/ following <domain>-monthly-<YYYY-MM>.md pattern
• Path construction: Uses pathlib.Path.home() for cross-platform compatibility across all skill modules

Frequently Asked Questions

Can I change the storage location for prospect data?

The current implementation hardcodes the ~/.geo-prospects/ path in scripts/webapp/app.py. To relocate the storage, you must modify the CRM_PATH, PROPOSALS_DIR, AUDITS_DIR, and REPORTS_DIR constants in that file, as these variables are referenced across the prospect, proposal, and compare skill modules.

What happens if I delete the ~/.geo-prospects/ directory?

Deleting this directory permanently removes all prospect records, generated proposals, audit history, and comparison reports. While the application will automatically recreate the directory structure on the next command execution, the data itself is not recoverable without external backups.

Are the proposal and report files human-readable?

Yes. According to skills/geo-proposal/SKILL.md and skills/geo-compare/SKILL.md, both proposals and monthly reports are stored as Markdown (.md) files. This format ensures readability in standard text editors, IDEs, and Markdown viewers without requiring specialized software.

How does the web application access prospect data?

The web UI invokes the load_prospects() function from scripts/webapp/app.py, which validates the existence of CRM_PATH and returns a JSON-parsed list of dictionaries. If ~/.geo-prospects/prospects.json does not exist, the function returns an empty list, allowing the application to initialize gracefully on first run.

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