dthash (Date-Time Hasher)

dthash is a secure, time-sensitive file identity utility. It generates unique 8-digit identifiers and full SHA-256 hashes by combining a file's absolute path with the precise microsecond timestamp of access.

It is designed for both human CLI usage and integration with LLM Agents (via MCP).

Features

• Time-Based Identity: Identical files generate different hashes at different times.
• Secure Handling: Auto-detects permission errors and handles sudo via secure stdin piping (POSIX only).
• Structured Output: Exports to JSON, CSV, or YAML.
• Decoding: Decodes generated config files to reveal original paths and timestamps.
• LLM Ready: Includes a built-in Model Context Protocol (MCP) server.

Installation

# Clone the repository
git clone [https://github.com/yourusername/datetime_hasher.git](https://github.com/yourusername/datetime_hasher.git)
cd datetime_hasher

# Install in editable mode
pip install -e .

# (Optional) Setup shell autocompletion
dthash-setup
source ~/.bashrc  # or ~/.zshrc

Usage

CLI

dthash [OPTIONS] FILE

EXAMPLES:

How to Load this in "Opencode" (OpenAI API / Custom Agents)

When you are working with OpenAI Assistants API or generic "Open Code" environments (where you manually define tools), you use the tool_definitions.json and AGENT_INSTRUCTIONS.md files.

The Workflow:

System Prompt: Read the content of AGENT_INSTRUCTIONS.md and paste it into the "System Instructions" or "System Prompt" field of your agent configuration.

Tool Definitions: Read the content of tool_definitions.json and paste it into the "Tools" or "Functions" definition block.

Python Example (using OpenAI library):

import json
from openai import OpenAI

# Load your definitions
with open("tool_definitions.json", "r") as f:
    tools_schema = json.load(f)

with open("AGENT_INSTRUCTIONS.md", "r") as f:
    system_instruction = f.read()

client = OpenAI()
assistant = client.beta.assistants.create(
    name="Data Hasher Agent",
    instructions=system_instruction,
    tools=tools_schema,
    model="gpt-4-turbo"
)

How to Use this in LLM Agents (MCP)

Claude-Code

import importlib.resources
# ... existing imports ...

@mcp.prompt()
def dthash_instructions() -> str:
    """Returns the system instructions for using dthash."""
    # This reads the file from src/dthash/resources/instructions.md
    try:
        resource = importlib.resources.files("dthash.resources").joinpath("instructions.md")
        return resource.read_text(encoding="utf-8")
    except Exception:
        return "Instructions not found. Please use generate_file_identity for hashing."

Claude-Desktop

1. Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

2. Add the server:

{
  "mcpServers": {
    "dthash": {
      "command": "uv",
      "args": ["run", "dthash-server"],
      "cwd": "/full/path/to/your/datetime_hasher"
    }
  }
}

USAGE

CLI

Generate a hash:

dthash /path/to/file

Decode a config file:

dthash --decode /path/to/output.json

Agent / MCP Usage

This tool exposes an MCP server for AI integration

• Tools: generate_file_identity, decode_file_identity
• Prompts: dthash_instructions

To run the server manually:

dthash-server

LICENSE

---

MIT License

Copyright (c) 2024 [Your Name/Organization]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.