A date tool should be included by default

[gianlucamazza]

Summary

Claude Code CLI should include a built-in date/time tool to enable better temporal context and time-aware operations without requiring additional setup or external dependencies.

Problem Statement

Claude often uses outdated temporal information in its responses, referencing dates from its training data (e.g., treating 2024 as "current year" when we're actually in 2025). This creates several issues:

• Incorrect temporal context: Claude may suggest outdated practices, deprecated APIs, or reference events as "recent" when they're actually old
• Wrong date calculations: When generating code or scripts, Claude might use hardcoded dates from 2024 instead of dynamic current dates
• Misleading information: Users receive contextually incorrect information about timeframes, deadlines, or version compatibility

Without access to current date/time, Claude cannot:

• Provide accurate temporal context for its responses
• Generate code with correct current timestamps
• Make appropriate assumptions about software versions, compatibility, or current best practices

Proposed Solution

Include a built-in date tool that provides Claude with real-time temporal context to ensure accurate and current responses.

Core Functionality

• Current date/time awareness: Enable Claude to know the actual current date and time
• Temporal context: Allow Claude to make informed decisions based on current timeframe
• Dynamic date generation: Generate code and responses with correct current timestamps
• Version/compatibility awareness: Help Claude suggest current best practices and compatible versions

Example Impact

Before (without date tool):

Claude: "In 2024, you should use Node.js 18..."
Claude: "This year (2024), the latest React version is..."

After (with date tool):

Claude: "As of June 2025, you should use Node.js 22..."
Claude: "Currently in 2025, the latest React version is..."

Benefits

1. Accurate temporal context: Claude provides responses based on current date/time instead of training data timestamps
2. Correct code generation: Generated scripts and applications use current dates instead of hardcoded old dates
3. Better recommendations: Claude can suggest current best practices, latest versions, and up-to-date approaches
4. Contextual awareness: Claude understands the actual timeline for project planning, deadlines, and scheduling

Use Cases

• Code generation: Creating scripts with current timestamps and dates
• Project planning: Accurate timeline suggestions and deadline calculations
• Version recommendations: Suggesting current stable versions of frameworks and tools
• Log analysis: Proper temporal context when analyzing recent vs. old log entries
• Documentation: Generating documentation with current dates and relevant timeframes
• API integration: Using current timestamps for API calls and data processing

Alternative Considerations

• Integration with existing system date tools
• Optional vs. mandatory inclusion
• Performance impact assessment
• Configuration options for default formats/timezones

Implementation Notes

• The tool should automatically provide current date/time context to Claude for every interaction
• Consider making this a default tool that's always available (similar to filesystem access)
• Should include timezone information and locale support
• Could be implemented as a simple tool that Claude can query when it needs temporal context
• Priority should be on providing accurate current date/time rather than complex date manipulation features

[patkepa]

Pretty sure that Claude 4 has today's date included inside of system prompt in each call?
https://docs.anthropic.com/en/release-notes/system-prompts

[dicksontsai]

You have a couple existing options here:

1. Instruct Claude to run Bash tool with the command date or date +"%Y-%m-%d"
2. Add a hook to review file output for old dates https://docs.anthropic.com/en/docs/claude-code/hooks.

By the way, @patkepa , Claude Code does not use the same system prompt as https://docs.anthropic.com/en/release-notes/system-prompts . As stated in that website, it applies to claude.ai and the mobile apps but not the Anthropic API. We do add the date to Claude Code's system prompt, but it may get lost in all the other context.

[gianlucamazza]

Reopening Discussion: A Production-Ready Date/Time Solution for Claude Code

@dicksontsai Thank you for your response. After researching how other AI coding tools handle this challenge and considering Claude Code's architecture, I'd like to propose a more comprehensive solution that addresses the root issues.

The Current Problem

You mentioned that the date "may get lost in all the other context" - this is precisely the issue. The current workarounds (manual date commands or hooks) are band-aids that don't address the fundamental problem: Claude needs reliable, automatic access to temporal context.

Research Findings

After analyzing how tools like Cursor, GitHub Copilot, and VS Code handle this:

• Cursor automatically injects contextual information into every interaction
• VS Code provides snippet variables like ${CURRENT_YEAR} that always work
• CLI tools commonly use environment injection for reliable context

Proposed Implementation

1. Enhanced Environment Context (Primary Solution)

Extend the existing <env> tag to always include temporal information:

<env>
Working directory: /Users/example/project
Platform: darwin
OS Version: Darwin 24.5.0
Today's date: 2025-01-02
Current time: 15:45:00 UTC
Timezone: America/New_York
Unix timestamp: 1735836300
</env>

Why this is the best approach:

• Zero configuration: Works immediately for all users
• Consistent: Follows Claude Code's existing patterns
• Testable: Can be mocked for testing
• Reliable: Never "lost in context" like system prompt additions

2. Dynamic Variables (Secondary Enhancement)

Support for template variables in prompts and code generation:

{{CURRENT_DATE}}     → 2025-01-02
{{CURRENT_TIME}}     → 15:45:00
{{CURRENT_ISO8601}}  → 2025-01-02T15:45:00Z
{{UNIX_TIMESTAMP}}   → 1735836300

3. Settings Configuration (User Control)

Allow users to configure date format preferences in .claude/settings.json:

{
  "datetime": {
    "format": "ISO8601",
    "timezone": "local",
    "includeInEnvironment": true
  }
}

Implementation Benefits

1. Accuracy: Eliminates outdated temporal references from training data
2. Performance: No additional tool calls needed
3. Consistency: Same date/time across entire conversation
4. Testing: Easy to mock for reproducible tests
5. Backwards Compatible: Doesn't break existing workflows

Real-World Impact

Currently, Claude often provides outdated information:

User: "What Node.js version should I use?"
Claude: "As of 2024, Node.js 20 is the latest LTS..."  # Wrong year!

With this implementation:

User: "What Node.js version should I use?"
Claude: "As of January 2025, Node.js 22 is the current LTS..."  # Accurate!

Technical Implementation

The implementation would be minimal:

// In environment context builder
interface EnvironmentContext {
  workingDirectory: string;
  platform: string;
  osVersion: string;
  currentDate: string;      // ISO date: "2025-01-02"
  currentTime: string;      // ISO time: "15:45:00"
  timezone: string;         // IANA timezone: "America/New_York"
  unixTimestamp: number;    // Unix timestamp: 1735836300
}

// Already proven to work - you did this for WebSearch in v1.0.36!

Addressing Concerns

"Just use bash date command"

• Requires Claude to remember to use it (often forgets)
• Adds latency to every date-related operation
• Inconsistent results due to execution timing

"Use hooks to catch old dates"

• Reactive, not preventive
• Doesn't help Claude make correct decisions initially
• Adds complexity for users

"It's in the system prompt"

• You acknowledged it gets lost - that's the problem we're solving
• Environment context is more reliable than system prompt

Community Need

This isn't an edge case. Common use cases include:

• Generating timestamps for logs and commits
• Creating date-based filenames
• Calculating relative dates ("3 days ago")
• Providing current version recommendations
• Writing time-sensitive documentation

Request

Given that:

1. You've already implemented date context for WebSearch (v1.0.36)
2. The current workarounds are inadequate
3. The implementation would be straightforward
4. This would significantly improve accuracy

Could we reopen this issue for proper implementation? I'm happy to contribute code or create a more detailed RFC if that would help.

The goal is simple: Make Claude Code as reliable with dates as it is with file paths.

[dicksontsai]

What we did for WebSearch in v1.0.36 was to tell it to look at today's date in . We didn't do anything extra.

The easiest way to contribute is not to provide a more detailed RFC but rather to write a hook demonstrating what 2 would look like.

Re-opening because "automatically injects contextual information into every interaction" seems like the most sensible solution to implement from the above.

[gianlucamazza]

Hi @dicksontsai! 👋

Thank you for the guidance on implementing a hook solution - it was exactly the push I needed to dive deeper into this.

I've spent some time building out what you suggested, and honestly, it turned into quite the rabbit hole (in a good way! 😅). Started with a simple hook and ended up with a comprehensive solution that I'm pretty excited about.

What I Built

I created two versions because I couldn't decide between "simple and fast" vs "comprehensive":

Smart Hook (my recommendation): Adds temporal context only when it makes sense - like when you're creating documentation or commit messages. Keeps the overhead minimal.

Complete Hook: Goes all-in with content guidance, template variables, and quality checks. It's more comprehensive but still lightweight.

Real-World Impact

The difference is honestly pretty striking:

• Before: "Last updated: April 2024" 😬
• After: "Last updated: 2025-07-03" ✅

Try It Out

# One-liner install if you want to test it
curl -sSL https://raw.githubusercontent.com/gianlucamazza/claude-code/feature/smart-temporal-context/smart-temporal-hook.sh -o ~/.claude/hooks/pre-tool-use.sh && chmod +x ~/.claude/hooks/pre-tool-use.sh

Repository with full details: https://github.com/gianlucamazza/claude-code/tree/feature/smart-temporal-context

I've been using it for a few days now and it feels natural - Claude just... knows what year it is! 😄

Would love to hear thoughts from you and the team. Happy to iterate on anything or answer questions.

Thanks again for the direction - this was a fun problem to solve! 🚀

[dicksontsai]

Thanks for trying out the idea! I like the setup but it actually won't work at the moment, since according to our documentation, Claude does not see stdout. Unfortunately, the results you see are likely a hallucination.

Your prototype illustrates that we should implement a Start hook #2876 to inject that basic temporal context at the start of an agent loop:

[DEBUG] Hook stdout: 📅 Enhanced Temporal Context:
Current Date: 2025-07-03
Current Time: 09:25:09 PDT
Timezone: PDT
Unix Timestamp: 1751559909

⚡ Basic temporal context ready!

🔧 Performance: 93Nms | Cache: enabled | Sm...

[dicksontsai]

With v1.0.55, you can now inject the current time using a UserPromptSubmit hook. Example: https://docs.anthropic.com/en/docs/claude-code/hooks#userpromptsubmit-example%3A-adding-context-and-validation (but ignore the validation part)