@jacques-ai/cli 0.0.7-alpha.1

package/hooks/adapters/tokenizer.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""
+tokenizer.py - Token Estimation Module for Jacques
+
+Uses tiktoken's cl100k_base encoding to estimate token counts.
+This encoding is used by OpenAI models and is reasonably close (~90%)
+to Claude's actual tokenizer.
+
+Provides:
+- Token count estimation from text
+- Model context window lookup
+- Context percentage calculation
+"""
+import sys
+
+# Cache encoder instance for performance
+_encoder = None
+
+
+def get_encoder():
+    """
+    Get cached tiktoken encoder.
+    
+    Uses cl100k_base encoding which is closest to Claude's tokenizer.
+    Encoder is cached for performance (~150k tokens/sec).
+    
+    Returns:
+        tiktoken.Encoding instance, or None if tiktoken not installed.
+    """
+    global _encoder
+    if _encoder is None:
+        try:
+            import tiktoken
+            _encoder = tiktoken.get_encoding("cl100k_base")
+        except ImportError:
+            print("[jacques:tokenizer] tiktoken not installed. Run: pip install tiktoken", file=sys.stderr)
+            return None
+    return _encoder
+
+
+def estimate_tokens(text: str) -> int:
+    """
+    Estimate token count for given text.
+    
+    Args:
+        text: Text to tokenize
+        
+    Returns:
+        Estimated token count, or character-based fallback if tiktoken unavailable.
+    """
+    if not text:
+        return 0
+    
+    encoder = get_encoder()
+    if encoder:
+        return len(encoder.encode(text))
+    
+    # Fallback: rough estimate of ~4 characters per token
+    return len(text) // 4
+
+
+# Model context windows (in tokens)
+# Source: Official documentation + Cursor UI observations
+MODEL_CONTEXT_WINDOWS = {
+    # Claude models (Cursor uses 176k for Claude in agent mode)
+    "claude-4.5-opus": 176_000,  # Cursor-specific limit
+    "claude-4.5-sonnet": 176_000,
+    "claude-4-opus": 176_000,
+    "claude-4-sonnet": 176_000,
+    "claude-3.5-sonnet": 176_000,
+    "claude-3-opus": 176_000,
+    "claude-3-sonnet": 176_000,
+    "claude-3-haiku": 176_000,
+    
+    # OpenAI models
+    "gpt-4o": 128_000,
+    "gpt-4-turbo": 128_000,
+    "gpt-4": 8_192,
+    "gpt-3.5-turbo": 16_385,
+    
+    # Google models
+    "gemini-2.5-pro": 1_000_000,
+    "gemini-2.5-flash": 1_000_000,
+    "gemini-1.5-pro": 2_000_000,
+    "gemini-1.5-flash": 1_000_000,
+    
+    # Default for unknown models (use Cursor's typical limit)
+    "default": 176_000,
+}
+
+
+def get_context_window(model: str) -> int:
+    """
+    Get context window size for a model.
+    
+    Args:
+        model: Model name/identifier
+        
+    Returns:
+        Context window size in tokens.
+    """
+    if not model:
+        return MODEL_CONTEXT_WINDOWS["default"]
+    
+    model_lower = model.lower()
+    
+    # Try exact match first
+    if model_lower in MODEL_CONTEXT_WINDOWS:
+        return MODEL_CONTEXT_WINDOWS[model_lower]
+    
+    # Try partial match
+    for key, window in MODEL_CONTEXT_WINDOWS.items():
+        if key != "default" and key in model_lower:
+            return window
+    
+    return MODEL_CONTEXT_WINDOWS["default"]
+
+
+def calculate_context_percentage(tokens: int, context_window: int) -> float:
+    """
+    Calculate context usage percentage.
+    
+    Args:
+        tokens: Current token count
+        context_window: Maximum context window size
+        
+    Returns:
+        Percentage of context used (0.0 to 100.0).
+    """
+    if context_window <= 0:
+        return 0.0
+    
+    percentage = (tokens / context_window) * 100
+    return min(percentage, 100.0)  # Cap at 100%
+
+
+def calculate_context_metrics(tokens: int, model: str) -> dict:
+    """
+    Calculate full context metrics for a given token count.
+    
+    Args:
+        tokens: Estimated token count
+        model: Model name for context window lookup
+        
+    Returns:
+        Dict with used_percentage, remaining_percentage, context_window_size.
+    """
+    context_window = get_context_window(model)
+    used_percentage = calculate_context_percentage(tokens, context_window)
+    
+    return {
+        "used_percentage": round(used_percentage, 1),
+        "remaining_percentage": round(100 - used_percentage, 1),
+        "context_window_size": context_window,
+        "estimated_tokens": tokens,
+    }
+
+
+# Thinking multipliers for extended thinking models
+# These models have internal "thinking" that's NOT in the transcript
+# but IS counted in the context. Empirically observed: ~4-6x for high-thinking.
+THINKING_MULTIPLIERS = {
+    "high-thinking": 5.0,  # Based on observed calibration factor of 5.68
+    "thinking": 3.0,       # Regular thinking models
+    "max": 2.0,            # Max mode may include more reasoning
+}
+
+
+def get_thinking_multiplier(model: str) -> float:
+    """
+    Get thinking multiplier for models with extended thinking.
+    
+    Extended thinking models have internal reasoning that doesn't
+    appear in the transcript but IS counted in Cursor's context.
+    
+    Args:
+        model: Model name/identifier
+        
+    Returns:
+        Multiplier to apply to transcript tokens (1.0 for non-thinking models).
+    """
+    if not model:
+        return 1.0
+    
+    model_lower = model.lower()
+    
+    # Check for thinking mode indicators
+    for mode, multiplier in THINKING_MULTIPLIERS.items():
+        if mode in model_lower:
+            return multiplier
+    
+    return 1.0

package/hooks/claude-code/pre-tool-use.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+"""
+pre-tool-use.py - Report pre-tool-use to Jacques
+
+Called on PreToolUse hook.
+Sends tool name to server so it can detect when Claude is waiting
+for user approval (edit acceptance, command approval, etc.).
+"""
+import sys
+from pathlib import Path
+
+# Add parent directory to path for adapter imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from adapters.claude_code import ClaudeCodeAdapter
+
+
+def main():
+    adapter = ClaudeCodeAdapter()
+
+    # Parse input from stdin
+    input_data = adapter.parse_input()
+    if not input_data:
+        sys.exit(0)
+
+    # Log for debugging (verify permission_mode presence)
+    adapter.log_debug(input_data, 'PreToolUse')
+
+    # Build and send pre_tool_use payload (no fallback - transient event)
+    payload = adapter.build_pre_tool_use_payload(input_data)
+    if payload:
+        adapter.send_event(payload, use_fallback=False)
+
+
+if __name__ == '__main__':
+    main()

package/hooks/claude-code/register-session.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""
+register-session.py - Register Claude Code session with Jacques
+
+Called on SessionStart hook.
+Registers new Claude Code session with the Jacques server.
+"""
+import sys
+from pathlib import Path
+
+# Add parent directory to path for adapter imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from adapters.claude_code import ClaudeCodeAdapter
+
+
+def main():
+    adapter = ClaudeCodeAdapter()
+    
+    # Parse input from stdin
+    input_data = adapter.parse_input()
+    if not input_data:
+        sys.exit(0)
+    
+    # Debug logging (remove after debugging complete)
+    adapter.log_debug(input_data, 'SessionStart')
+    
+    # Build and send session_start payload
+    payload = adapter.build_session_start_payload(input_data)
+    if payload:
+        adapter.send_event(payload, use_fallback=True)
+
+
+if __name__ == '__main__':
+    main()

package/hooks/claude-code/report-activity.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""
+report-activity.py - Report Claude Code activity to Jacques
+
+Called on PostToolUse hook.
+Updates session activity timestamp and refreshes session title.
+"""
+import sys
+from pathlib import Path
+
+# Add parent directory to path for adapter imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from adapters.claude_code import ClaudeCodeAdapter
+
+
+def main():
+    adapter = ClaudeCodeAdapter()
+    
+    # Parse input from stdin
+    input_data = adapter.parse_input()
+    if not input_data:
+        sys.exit(0)
+    
+    # Build and send activity payload (no fallback for activity events)
+    payload = adapter.build_activity_payload(input_data)
+    if payload:
+        adapter.send_event(payload, use_fallback=False)
+
+
+if __name__ == '__main__':
+    main()

package/hooks/claude-code/session-idle.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""
+session-idle.py - Mark Claude Code session as idle
+
+Called on Stop hook.
+Marks session as idle (waiting for user input).
+"""
+import sys
+from pathlib import Path
+
+# Add parent directory to path for adapter imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from adapters.claude_code import ClaudeCodeAdapter
+
+
+def main():
+    adapter = ClaudeCodeAdapter()
+    
+    # Parse input from stdin
+    input_data = adapter.parse_input()
+    if not input_data:
+        sys.exit(0)
+    
+    # Build and send idle payload
+    payload = adapter.build_idle_payload(input_data)
+    if payload:
+        adapter.send_event(payload, use_fallback=False)
+
+
+if __name__ == '__main__':
+    main()

package/hooks/claude-code/statusline.sh

@@ -0,0 +1,91 @@
+#!/bin/bash
+#
+# Jacques statusLine Script
+#
+# Receives JSON from Claude Code's statusLine feature via stdin.
+# Extracts session_id and context_window data.
+# Sends context update to Jacques server via Unix socket.
+# Displays abbreviated status for Claude Code's status bar.
+#
+
+# DEBUG: Log that the script started (helps debug Cursor issues)
+echo "$(date '+%Y-%m-%d %H:%M:%S') SCRIPT_START" >> /tmp/jacques-statusline-debug.log
+
+# Read all input from stdin
+input=$(cat)
+
+# Exit if no input
+if [ -z "$input" ]; then
+  exit 0
+fi
+
+# DEBUG: Log the raw JSON input to help diagnose field path issues
+# Remove this line after debugging is complete
+echo "$(date '+%Y-%m-%d %H:%M:%S') $input" >> /tmp/jacques-statusline-debug.log
+
+# Extract key fields using jq
+# Note: Claude Code sends null for percentages at session start, we need to handle this
+session_id=$(echo "$input" | jq -r '.session_id // empty')
+
+# Handle null values explicitly - jq outputs "null" string for null values even with // fallback in some cases
+used_pct_raw=$(echo "$input" | jq -r '.context_window.used_percentage')
+remaining_pct_raw=$(echo "$input" | jq -r '.context_window.remaining_percentage')
+
+# Convert null/empty to 0 for used_percentage
+if [ "$used_pct_raw" = "null" ] || [ -z "$used_pct_raw" ]; then
+  used_pct=0
+else
+  used_pct=$used_pct_raw
+fi
+
+# Convert null/empty to 100 for remaining_percentage  
+if [ "$remaining_pct_raw" = "null" ] || [ -z "$remaining_pct_raw" ]; then
+  remaining_pct=100
+else
+  remaining_pct=$remaining_pct_raw
+fi
+
+ctx_size=$(echo "$input" | jq -r '.context_window.context_window_size // 0')
+total_input=$(echo "$input" | jq -r '.context_window.total_input_tokens // 0')
+total_output=$(echo "$input" | jq -r '.context_window.total_output_tokens // 0')
+model=$(echo "$input" | jq -r '.model.id // "unknown"')
+model_display=$(echo "$input" | jq -r '.model.display_name // "Unknown"')
+cwd=$(echo "$input" | jq -r '.workspace.current_dir // .cwd // ""')
+project_dir=$(echo "$input" | jq -r '.workspace.project_dir // ""')
+
+# Only proceed if we have a session_id
+if [ -z "$session_id" ]; then
+  # No session_id, just show basic status
+  printf "ctx:?%%"
+  exit 0
+fi
+
+# Send to Jacques server (if socket exists and server is running)
+if [ -S /tmp/jacques.sock ]; then
+  # Build JSON payload
+  timestamp=$(( $(date +%s) * 1000 ))
+  payload=$(cat <<EOF
+{"event":"context_update","session_id":"$session_id","used_percentage":$used_pct,"remaining_percentage":$remaining_pct,"context_window_size":$ctx_size,"total_input_tokens":$total_input,"total_output_tokens":$total_output,"model":"$model","model_display_name":"$model_display","cwd":"$cwd","project_dir":"$project_dir","timestamp":$timestamp}
+EOF
+)
+  
+  # Send to socket (non-blocking, ignore errors)
+  echo "$payload" | nc -U /tmp/jacques.sock 2>/dev/null &
+fi
+
+# Display abbreviated status in Claude Code status bar
+# Format: [Model] ctx:XX%
+# Round percentage for display
+used_int=${used_pct%.*}
+if [ -z "$used_int" ]; then
+  used_int="0"
+fi
+
+# Add warning indicator if context is high
+if [ "$used_int" -ge 80 ]; then
+  printf "[%s] ctx:%s%% ⚠️" "$model_display" "$used_int"
+elif [ "$used_int" -ge 60 ]; then
+  printf "[%s] ctx:%s%%" "$model_display" "$used_int"
+else
+  printf "[%s] ctx:%s%%" "$model_display" "$used_int"
+fi

package/hooks/claude-code/unregister-session.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""
+unregister-session.py - Unregister Claude Code session from Jacques
+
+Called on SessionEnd hook.
+Removes session from Jacques server.
+"""
+import sys
+from pathlib import Path
+
+# Add parent directory to path for adapter imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from adapters.claude_code import ClaudeCodeAdapter
+
+
+def main():
+    adapter = ClaudeCodeAdapter()
+    
+    # Parse input from stdin
+    input_data = adapter.parse_input()
+    if not input_data:
+        sys.exit(0)
+    
+    # Build and send session_end payload
+    payload = adapter.build_session_end_payload(input_data)
+    if payload:
+        adapter.send_event(payload, use_fallback=False)
+
+
+if __name__ == '__main__':
+    main()

package/hooks/cursor/README.md

@@ -0,0 +1,61 @@
+# Cursor Hooks for Jacques
+
+This directory contains hooks for integrating Cursor Native AI with Jacques.
+
+## Installation
+
+### Option 1: Automatic (Recommended)
+
+```bash
+cd /path/to/jacques-context-manager
+python3 hooks/install.py --source cursor
+```
+
+### Option 2: Manual
+
+1. Copy the hooks to `~/.jacques/hooks/cursor/`:
+
+   ```bash
+   mkdir -p ~/.jacques/hooks/cursor
+   cp hooks/cursor/*.py ~/.jacques/hooks/cursor/
+   cp -r hooks/adapters ~/.jacques/hooks/
+   ```
+
+2. Copy `hooks.json.template` to your project's `.cursor/hooks.json`:
+
+   ```bash
+   cp hooks/cursor/hooks.json.template /path/to/your/project/.cursor/hooks.json
+   ```
+
+   Or for global configuration, copy to Cursor's config directory.
+
+## Hooks
+
+| Hook         | Event            | Description                               |
+| ------------ | ---------------- | ----------------------------------------- |
+| sessionStart | `session_start`  | Registers new Cursor session with Jacques |
+| sessionEnd   | `session_end`    | Unregisters Cursor session from Jacques   |
+| postToolUse  | `activity`       | Reports tool usage activity               |
+| preCompact   | `context_update` | **Key hook!** Provides context metrics    |
+
+## Context Metrics
+
+The `preCompact` hook is special - it provides context window usage metrics,
+allowing Jacques to display context percentage for Cursor sessions just like
+Claude Code CLI sessions.
+
+Expected fields from Cursor's preCompact event:
+
+- `context_usage_percent`: Percentage of context used (0-100)
+- `context_tokens`: Current token count
+- `context_window_size`: Maximum context window size
+
+## Debugging
+
+Check the debug log for hook input data:
+
+```bash
+tail -f /tmp/jacques-hook-debug.log
+```
+
+This helps understand what data Cursor is sending to hooks.

package/hooks/cursor/after-agent-response.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""
+after-agent-response.py - Estimate context usage after each AI response
+
+Called on Cursor's afterAgentResponse hook.
+Reads the transcript file to estimate current token usage.
+
+This hook fires after EVERY AI response, allowing us to show
+real-time context estimates instead of waiting for preCompact.
+
+Flow:
+1. Parse input (contains transcript_path)
+2. Read transcript file content
+3. Estimate tokens using tiktoken
+4. Add skill overhead (not in transcript but always in context)
+5. Apply calibration factor if available
+6. Send context_update with estimated percentage
+"""
+import sys
+from pathlib import Path
+
+# Add parent directory to path for adapter imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from adapters.cursor import CursorAdapter
+from adapters import tokenizer, calibration, skills
+
+
+def main():
+    adapter = CursorAdapter()
+    
+    # Parse input from stdin
+    input_data = adapter.parse_input()
+    if not input_data:
+        sys.exit(0)
+    
+    # Debug logging
+    adapter.log_debug(input_data, 'afterAgentResponse')
+    
+    # Get transcript path
+    transcript_path = input_data.get('transcript_path')
+    if not transcript_path:
+        # No transcript available - can't estimate
+        # Stay silent rather than guessing
+        sys.exit(0)
+    
+    transcript_file = Path(transcript_path)
+    if not transcript_file.exists():
+        sys.exit(0)
+    
+    # Read transcript content
+    try:
+        content = transcript_file.read_text(encoding='utf-8')
+    except Exception as e:
+        print(f"[jacques:after-agent-response] Error reading transcript: {e}", file=sys.stderr)
+        sys.exit(0)
+    
+    if not content:
+        sys.exit(0)
+    
+    # Estimate tokens from transcript
+    transcript_tokens = tokenizer.estimate_tokens(content)
+    
+    # Get model info
+    model = adapter.get_model(input_data)
+    
+    # Apply thinking multiplier for extended thinking models
+    # Thinking blocks are NOT in transcript but ARE in context
+    thinking_multiplier = tokenizer.get_thinking_multiplier(model)
+    adjusted_transcript_tokens = int(transcript_tokens * thinking_multiplier)
+    
+    # Add skill overhead (always in context but not in transcript)
+    initial_estimate = skills.get_initial_context_estimate(model)
+    skill_overhead = initial_estimate['total_initial_tokens']
+    
+    # Total = adjusted transcript + skills + system prompts
+    total_tokens = adjusted_transcript_tokens + skill_overhead
+    
+    # Get session ID for calibration
+    session_id = input_data.get('conversation_id')
+    
+    if session_id:
+        # Apply calibration factor if available (further refinement)
+        factor = calibration.get_factor(session_id)
+        total_tokens = int(total_tokens * factor)
+        
+        # Store this estimate for future calibration
+        calibration.set_last_estimate(session_id, total_tokens)
+    
+    # Build and send context estimate payload
+    payload = adapter.build_context_estimate_payload(input_data, total_tokens, model)
+    if payload:
+        adapter.send_event(payload, use_fallback=False)
+
+
+if __name__ == '__main__':
+    main()

package/hooks/cursor/hooks.json.template

@@ -0,0 +1,30 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "python3 ~/.jacques/hooks/cursor/session-start.py"
+      }
+    ],
+    "sessionEnd": [
+      {
+        "command": "python3 ~/.jacques/hooks/cursor/session-end.py"
+      }
+    ],
+    "postToolUse": [
+      {
+        "command": "python3 ~/.jacques/hooks/cursor/post-tool-use.py"
+      }
+    ],
+    "preCompact": [
+      {
+        "command": "python3 ~/.jacques/hooks/cursor/pre-compact.py"
+      }
+    ],
+    "afterAgentResponse": [
+      {
+        "command": "python3 ~/.jacques/hooks/cursor/after-agent-response.py"
+      }
+    ]
+  }
+}

package/hooks/cursor/post-tool-use.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""
+post-tool-use.py - Report Cursor activity to Jacques
+
+Called on Cursor's postToolUse hook.
+Updates session activity timestamp.
+"""
+import sys
+from pathlib import Path
+
+# Add parent directory to path for adapter imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from adapters.cursor import CursorAdapter
+
+
+def main():
+    adapter = CursorAdapter()
+    
+    # Parse input from stdin
+    input_data = adapter.parse_input()
+    if not input_data:
+        sys.exit(0)
+    
+    # Build and send activity payload (no fallback for activity events)
+    payload = adapter.build_activity_payload(input_data)
+    if payload:
+        adapter.send_event(payload, use_fallback=False)
+
+
+if __name__ == '__main__':
+    main()