data-access-patterns

Data Access Patterns

IMPORTANT: Placeholder Notation

This document uses placeholder syntax to indicate values that must be substituted from your agent prompt:

• {SCRIPTS_PATH} - Replace with the actual SCRIPTS_PATH value from your prompt
• ${CLAUDE_SESSION_ID} - Replace with the actual session ID from your prompt

These are NOT bash environment variables. They are text placeholders documenting what values you should use.

Example:

• Documentation shows: bun "{SCRIPTS_PATH}/task-get.js" --session ${CLAUDE_SESSION_ID}
• Your prompt provides: SCRIPTS_PATH: /Users/name/.claude/plugins/.../scripts and CLAUDE_SESSION_ID: abc-123
• You should execute: bun "/Users/name/.claude/plugins/.../scripts/task-get.js" --session abc-123

Core Rule: JSON via Scripts, Markdown via Read

Always use scripts for JSON data. Never use Read tool directly on JSON files.

Data Type	Access Method	Tool
session.json	session-get.js	Bash
context.json	context-get.js	Bash
tasks/*.json	task-get.js, task-list.js	Bash
exploration/*.md	Direct file read	Read
docs/plans/*.md	Direct file read	Read

Why Scripts for JSON?

1. Token Efficiency

JSON structure wastes significant context tokens:

{
  "version": "6.1",
  "session_id": "abc-123",
  "working_dir": "/path/to/project",
  "phase": "PLANNING",
  "exploration_stage": "overview",
  ...
}

Every brace, quote, comma, and key name consumes tokens. For large session files with evidence arrays, this can waste thousands of tokens.

Script output with --field flag:

bun "{SCRIPTS_PATH}/session-get.js" --session ${CLAUDE_SESSION_ID} --field phase
# Output: PLANNING

Returns only the value you need—no JSON structure overhead.

2. Field Extraction

Scripts support precise data extraction:

# Single field
bun "{SCRIPTS_PATH}/session-get.js" --session ${CLAUDE_SESSION_ID} --field phase

# Nested field (dot notation)
bun "{SCRIPTS_PATH}/session-field.js" --session ${CLAUDE_SESSION_ID} --field options.auto_mode

# AI-friendly summary
bun "{SCRIPTS_PATH}/context-get.js" --session ${CLAUDE_SESSION_ID} --summary