ralph.rb 1.2.4355354345 → 2.0.0

data/specs/cli.md

@@ -1,223 +1,16 @@
-# CLI Specification
+# CLI specification
 
-Ralph is invoked as a single binary with positional arguments, flags, and subcommands.
+How will we interact with the program?
 
-```
-ralph "<prompt>" [options]
-ralph <subcommand> [args]
-```
-
-## Prompt Input
-
-The primary argument is a prompt string describing the task for the AI agent.
-
-| Input method | Syntax | Notes |
-|---|---|---|
-| Inline string | `ralph "Build a REST API"` | One or more positional args joined with spaces |
-| Piped input | `cat prompt.md \| ralph` | Read prompt from stdin via shell pipe |
-| Command substitution | `ralph $(cat prompt.md)` | Expand file contents as arguments |
-
-### Prompt resolution order
-
-1. Join all positional args with spaces.
-2. If the resolved prompt is empty, exit with an error.
-
-## Loop Options
-
-These flags configure the main iteration loop.
-
-### `--agent AGENT`
-
-Select the AI agent to use.
-
-- **Type:** String, restricted to valid agent names
-- **Valid values:** `opencode`, `claude-code`, `codex`
-- **Default:** `opencode`
-- **Error on invalid value:** Yes (OptionParser rejects with `invalid argument`)
-
-### `--min-iterations N`
-
-Minimum number of iterations before a completion promise is accepted.
-
-- **Type:** Integer
-- **Default:** `1`
-- **Behavior:** If the agent outputs the completion promise before this many iterations have run, the loop continues anyway.
-
-### `--max-iterations N`
-
-Maximum number of iterations before the loop stops automatically.
-
-- **Type:** Integer
-- **Default:** `0` (unlimited)
-- **Behavior:** When the iteration counter exceeds this value, the loop stops and clears state.
-
-### Validation
-
-`--min-iterations` must not exceed `--max-iterations` (when max > 0). The CLI exits with an error if this constraint is violated.
-
-### `--completion-promise TEXT`
-
-The phrase the agent must output (wrapped in `<promise>...</promise>` tags) to signal task completion.
-
-- **Type:** String
-- **Default:** `COMPLETE`
-
-### `--tasks`, `-t`
-
-Enable Tasks Mode for structured task tracking.
-
-- **Type:** Boolean flag
-- **Default:** `false`
-- **Behavior:** When enabled, the loop works through tasks defined in `.ralph/ralph-tasks.md` one at a time. The prompt builder includes task-specific instructions and workflow guidance.
-
-### `--task-promise TEXT`
-
-The phrase the agent outputs to signal an individual task is complete (tasks mode only).
-
-- **Type:** String
-- **Default:** `READY_FOR_NEXT_TASK`
-
-### `--model MODEL`
-
-Model identifier passed to the selected agent.
-
-- **Type:** String
-- **Default:** `""` (agent's default)
-- **Agent-specific:** The value is passed directly to the agent CLI (e.g., `--model` for claude-code/codex, `-m` for opencode).
-
-### `--[no-]stream`
-
-Control whether agent output is streamed in real-time or buffered.
-
-- **Type:** Boolean
-- **Default:** `true` (streaming on)
-- **`--stream`:** Stream stdout/stderr in real-time with tool counting and heartbeat.
-- **`--no-stream`:** Buffer all output, print at end. Tool counts collected post-hoc.
-
-### `--verbose-tools`
-
-Print every tool invocation line instead of periodic compact summaries.
-
-- **Type:** Boolean flag
-- **Default:** `false`
-- **Behavior:** When off (default), tool lines are suppressed and a compact summary is printed every 3 seconds. When on, every tool line is printed as-is.
-
-### `--no-plugins`
-
-Disable non-auth OpenCode plugins for the current run.
-
-- **Type:** Boolean flag
-- **Default:** `false`
-- **Agent-specific:** Only affects `opencode`. Prints a warning if used with `claude-code` or `codex`.
-- **Behavior:** Generates a filtered OpenCode config that only includes plugins matching `/auth/i`.
-
-### `--[no-]commit`
-
-Control automatic git commits after each iteration.
-
-- **Type:** Boolean
-- **Default:** `true` (auto-commit on)
-- **`--commit`:** After each iteration, if `git status --porcelain` shows changes, run `git add -A && git commit -m "Ralph iteration N: work in progress"`.
-- **`--no-commit`:** Skip auto-commits.
-
-### `--[no-]allow-all`
-
-Control automatic tool permission approval.
-
-- **Type:** Boolean
-- **Default:** `true` (auto-approve on)
-- **`--allow-all`:** Pass permission flags to the agent (`--dangerously-skip-permissions` for claude-code, `--full-auto` for codex, permission config for opencode).
-- **`--no-allow-all`:** Require interactive permission prompts from the agent.
-
-## Subcommands
-
-Subcommands are flag-style (prefixed with `--`) and cause the CLI to perform a specific action then exit. They do not start the main loop.
-
-### `--version`, `-v`
-
-Print `ralph <VERSION>` and exit 0.
-
-### `--help`, `-h`
-
-Print the full help text (generated by OptionParser) and exit 0.
-
-### `--status`
-
-Display the current loop status, pending context, and iteration history, then exit 0.
-
-- **With `-t` or `--tasks`:** Also display the current task list from `.ralph/ralph-tasks.md`.
-- **When an active loop has `tasks_mode` enabled:** Task list is shown automatically.
-- **Output includes:**
-  - Active/inactive status
-  - Current iteration, start time, elapsed time
-  - Completion promise, agent, model
-  - Pending context (if any)
-  - Task list with progress (if shown)
-  - Last 5 iterations with duration and top tools
-  - Struggle indicators (if detected)
-
-### `--add-context TEXT`
-
-Append context text to `.ralph/ralph-context.md` for the next iteration.
-
-- **Requires:** A text argument (exits with error if missing)
-- **Behavior:** Appends a timestamped section. Creates the file if it doesn't exist. The context is injected into the prompt on the next iteration, then cleared.
-
-### `--clear-context`
-
-Delete `.ralph/ralph-context.md` if it exists.
-
-### `--list-tasks`
-
-Parse and display tasks from `.ralph/ralph-tasks.md` with numbered indices and status icons.
-
-- Exits with a message if no tasks file exists.
-
-### `--add-task DESC`
-
-Append a new `- [ ] DESC` line to `.ralph/ralph-tasks.md`.
-
-- **Requires:** A description argument.
-- Creates the file with a header if it doesn't exist.
-
-### `--remove-task N`
-
-Remove task at 1-based index N (including its subtasks) from `.ralph/ralph-tasks.md`.
-
-- **Requires:** An integer argument.
-- **Validation:** Index must be in range `1..task_count`.
-- **Behavior:** Removes the top-level task line and any indented lines immediately following it (subtasks/notes).
-
-## Error Handling
-
-| Condition | Behavior |
-|---|---|
-| Unknown option | Exit 1, print message + `Run 'ralph --help'` |
-| Invalid option value (bad agent, non-integer) | Exit 1, OptionParser error message + `Run 'ralph --help'` |
-| No prompt provided | Exit 1, print usage hint |
-| min-iterations > max-iterations | Exit 1, print constraint error |
-| Agent CLI not found in PATH | Exit 1, print which agent is missing |
-| Loop already active | Exit 1, print active loop info and state file path |
-| Fatal error during loop | Exit 1, clear state, print error |
-
-## Options Hash
+## overview
 
-After parsing, the CLI produces an options hash passed to `Ralph::Loop.run`:
+Keep it simple stupid!! Unix is king, and we live by their philosophy
 
-```ruby
-{
-  prompt: String,              # resolved prompt text
-  min_iterations: Integer,     # >= 1
-  max_iterations: Integer,     # 0 = unlimited
-  completion_promise: String,  # default "COMPLETE"
-  tasks_mode: Boolean,         # default false
-  task_promise: String,        # default "READY_FOR_NEXT_TASK"
-  model: String,               # default ""
-  chosen_agent: String,          # default "opencode"
-  auto_commit: Boolean,        # default true
-  disable_plugins: Boolean,    # default false
-  allow_all_permissions: Boolean, # default true
-  stream_output: Boolean,      # default true
-  verbose_tools: Boolean,      # default false
-}
+```sh
+cat my-prompt-file.md | ralph "more prompt details" \
+  --model=opus-4.5 \
+  --max-iterations=10 \
+  --duration=10 \
+  --max-context=80000 \
+  --completion="<promise>COMPLETE</promise>"
 ```

data/specs/lib/todo_item.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2025 Nathan Kidd <nathankidd@hey.com>. All rights reserved.
+# SPDX-License-Identifier: Proprietary
+
+require 'json'
+require 'time'
+
+# Represents a single todo item with full feature support
+class TodoItem
+  attr_reader :id, :title, :description, :created_at, :updated_at
+  attr_accessor :completed, :priority, :due_date, :tags, :category
+
+  PRIORITIES = { low: 1, medium: 2, high: 3, urgent: 4 }.freeze
+
+  def initialize(title:, description: nil, priority: :medium, due_date: nil, tags: [], category: nil, id: nil)
+    @id = id || generate_id
+    @title = title
+    @description = description
+    @completed = false
+    @priority = priority
+    @due_date = due_date
+    @tags = tags || []
+    @category = category
+    @created_at = Time.now
+    @updated_at = Time.now
+  end
+
+  def complete!
+    if @completed
+      @completed = false
+    else
+      @completed = true
+    end
+    @updated_at = Time.now
+  end
+
+  def completed?
+    @completed
+  end
+
+  def overdue?
+    if @due_date && !@completed
+      Time.parse(@due_date) < Time.now
+    else
+      false
+    end
+  end
+
+  def due_soon?(hours: 24)
+    if @due_date && !@completed
+      due_time = Time.parse(@due_date)
+      due_time > Time.now && due_time < Time.now + (hours * 3600)
+    else
+      false
+    end
+  end
+
+  def priority_value
+    PRIORITIES[@priority] || PRIORITIES[:medium]
+  end
+
+  def add_tag(tag)
+    unless @tags.include?(tag)
+      @tags << tag
+      @updated_at = Time.now
+    end
+  end
+
+  def remove_tag(tag)
+    if @tags.delete(tag)
+      @updated_at = Time.now
+    end
+  end
+
+  def matches_filter?(query: nil, tags: nil, category: nil, completed: nil, priority: nil)
+    if query && !matches_query?(query)
+      false
+    elsif tags && (tags & @tags).empty?
+      false
+    elsif category && @category != category
+      false
+    elsif !completed.nil? && @completed != completed
+      false
+    elsif priority && @priority != priority
+      false
+    else
+      true
+    end
+  end
+
+  def to_h
+    {
+      id: @id,
+      title: @title,
+      description: @description,
+      completed: @completed,
+      priority: @priority,
+      due_date: @due_date,
+      tags: @tags,
+      category: @category,
+      created_at: @created_at.iso8601,
+      updated_at: @updated_at.iso8601
+    }
+  end
+
+  def self.from_h(hash)
+    new(
+      id: hash['id'],
+      title: hash['title'],
+      description: hash['description'],
+      priority: hash['priority']&.to_sym || :medium,
+      due_date: hash['due_date'],
+      tags: hash['tags'] || [],
+      category: hash['category']
+    ).then do |item|
+      item.instance_variable_set(:@completed, hash['completed'] || false)
+      item.instance_variable_set(:@created_at, Time.parse(hash['created_at']))
+      item.instance_variable_set(:@updated_at, Time.parse(hash['updated_at']))
+      item
+    end
+  end
+
+  private
+
+  def generate_id
+    "#{Time.now.to_i}-#{rand(10000)}"
+  end
+
+  def matches_query?(query)
+    query_lower = query.downcase
+    if @title.downcase.include?(query_lower)
+      true
+    elsif @description && @description.downcase.include?(query_lower)
+      true
+    elsif @tags.any? { |tag| tag.downcase.include?(query_lower) }
+      true
+    elsif @category && @category.downcase.include?(query_lower)
+      true
+    else
+      false
+    end
+  end
+end

data/specs/log

@@ -0,0 +1,15 @@
+{"type":"step_start","timestamp":1770187082911,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f4c89001ZPPQ0fLyoVyI6R","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f17af001hBx2ZnI5s2T7X6","type":"step-start","snapshot":"b743fc3bfaf58816da3d0e322f5af92274b3318c"}}
+{"type":"text","timestamp":1770187082912,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f4c8b001bqAW435IjTqIWL","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f17af001hBx2ZnI5s2T7X6","type":"text","text":"I'll build you a comprehensive super todo app! Let me create a solid Ruby implementation with all the features you'd want.","time":{"start":1770187082902,"end":1770187082902}}}
+{"type":"tool_use","timestamp":1770187087186,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f4c970017d4K2HeeM44TrY","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f17af001hBx2ZnI5s2T7X6","type":"tool","callID":"toolu_013ZVQg5YJHMYqKHav9rKXUu","tool":"todowrite","state":{"status":"completed","input":{"todos":[{"id":"1","content":"Design the todo app architecture and data model","status":"in_progress","priority":"high"},{"id":"2","content":"Implement core Todo and TodoList classes","status":"pending","priority":"high"},{"id":"3","content":"Add persistence layer (JSON file storage)","status":"pending","priority":"high"},{"id":"4","content":"Create CLI interface with command handling","status":"pending","priority":"high"},{"id":"5","content":"Add filtering and search capabilities","status":"pending","priority":"medium"},{"id":"6","content":"Implement priority levels and due dates","status":"pending","priority":"medium"},{"id":"7","content":"Add tags and categories","status":"pending","priority":"medium"},{"id":"8","content":"Create pretty output formatting","status":"pending","priority":"medium"},{"id":"9","content":"Write comprehensive tests","status":"pending","priority":"high"},{"id":"10","content":"Add README with usage examples","status":"pending","priority":"low"}]},"output":"[\n  {\n    \"id\": \"1\",\n    \"content\": \"Design the todo app architecture and data model\",\n    \"status\": \"in_progress\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"2\",\n    \"content\": \"Implement core Todo and TodoList classes\",\n    \"status\": \"pending\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"3\",\n    \"content\": \"Add persistence layer (JSON file storage)\",\n    \"status\": \"pending\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"4\",\n    \"content\": \"Create CLI interface with command handling\",\n    \"status\": \"pending\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"5\",\n    \"content\": \"Add filtering and search capabilities\",\n    \"status\": \"pending\",\n    \"priority\": \"medium\"\n  },\n  {\n    \"id\": \"6\",\n    \"content\": \"Implement priority levels and due dates\",\n    \"status\": \"pending\",\n    \"priority\": \"medium\"\n  },\n  {\n    \"id\": \"7\",\n    \"content\": \"Add tags and categories\",\n    \"status\": \"pending\",\n    \"priority\": \"medium\"\n  },\n  {\n    \"id\": \"8\",\n    \"content\": \"Create pretty output formatting\",\n    \"status\": \"pending\",\n    \"priority\": \"medium\"\n  },\n  {\n    \"id\": \"9\",\n    \"content\": \"Write comprehensive tests\",\n    \"status\": \"pending\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"10\",\n    \"content\": \"Add README with usage examples\",\n    \"status\": \"pending\",\n    \"priority\": \"low\"\n  }\n]","title":"10 todos","metadata":{"todos":[{"id":"1","content":"Design the todo app architecture and data model","status":"in_progress","priority":"high"},{"id":"2","content":"Implement core Todo and TodoList classes","status":"pending","priority":"high"},{"id":"3","content":"Add persistence layer (JSON file storage)","status":"pending","priority":"high"},{"id":"4","content":"Create CLI interface with command handling","status":"pending","priority":"high"},{"id":"5","content":"Add filtering and search capabilities","status":"pending","priority":"medium"},{"id":"6","content":"Implement priority levels and due dates","status":"pending","priority":"medium"},{"id":"7","content":"Add tags and categories","status":"pending","priority":"medium"},{"id":"8","content":"Create pretty output formatting","status":"pending","priority":"medium"},{"id":"9","content":"Write comprehensive tests","status":"pending","priority":"high"},{"id":"10","content":"Add README with usage examples","status":"pending","priority":"low"}],"truncated":false},"time":{"start":1770187087172,"end":1770187087180}}}}
+{"type":"step_finish","timestamp":1770187087202,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f5d51001K0X6r5is6bSpCF","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f17af001hBx2ZnI5s2T7X6","type":"step-finish","reason":"tool-calls","snapshot":"a57194ef5a651225fcd30a8c1693512e5ac64d59","cost":0,"tokens":{"input":2,"output":392,"reasoning":0,"cache":{"read":0,"write":15463}}}}
+{"type":"step_start","timestamp":1770187100723,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f9230001va5bdY1KhjxQG0","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f5d7a001ahslHtCQnw7J1X","type":"step-start","snapshot":"cdd7b1abdd3f43bd9efb116cffba98955ba57a2e"}}
+{"type":"tool_use","timestamp":1770187100734,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f9234001Uu930gEHD2BlmN","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f5d7a001ahslHtCQnw7J1X","type":"tool","callID":"toolu_01EYZZEC8oyTLrULZrUsUEx2","tool":"read","state":{"status":"completed","input":{"filePath":"/home/nathan/src/ralph.rb/specs/README.md"},"output":"<file>\n00001| <!--\n00002|  Copyright (c) 2025 Nathan Kidd <nathankidd@hey.com>. All rights reserved.\n00003|  SPDX-License-Identifier: Proprietary\n00004| -->\n00005| \n00006| <!--\n00007|   HOW TO MAINTAIN THIS FILE\n00008| \n00009|   This is the index of all design specifications for Ralph.rb.\n00010|   Each row links a spec document to its implementation code and a short purpose summary.\n00011| \n00012|   When adding a new spec:\n00013|   1. Create the markdown file in this directory (specs/)\n00014|   2. Add a row to the appropriate table section below\n00015|   3. Link the spec file, the code path it describes, and a brief purpose\n00016| \n00017|   Table format:\n00018|     | [spec-name.md](./spec-name.md) | [path/to/code](../path/to/code) | Short description |\n00019| \n00020|   Use \"—\" in the Code column if the spec has no implementation yet.\n00021|   Group specs under heading sections by domain area.\n00022| -->\n00023| \n00024| # Ralph.rb Specifications\n00025| \n00026| Design documentation for Ralph.rb, a Ruby CLI that runs iterative AI development loops.\n00027| \n00028| ## Core\n00029| \n00030| | Spec | Code | Purpose |\n00031| |------|------|---------|\n00032| \n\n(End of file - total 32 lines)\n</file>","title":"specs/README.md","metadata":{"preview":"<!--\n Copyright (c) 2025 Nathan Kidd <nathankidd@hey.com>. All rights reserved.\n SPDX-License-Identifier: Proprietary\n-->\n\n<!--\n  HOW TO MAINTAIN THIS FILE\n\n  This is the index of all design specifications for Ralph.rb.\n  Each row links a spec document to its implementation code and a short purpose summary.\n\n  When adding a new spec:\n  1. Create the markdown file in this directory (specs/)\n  2. Add a row to the appropriate table section below\n  3. Link the spec file, the code path it describes, and a brief purpose\n\n  Table format:\n    | [spec-name.md](./spec-name.md) | [path/to/code](../path/to/code) | Short description |\n\n  Use \"—\" in the Code column if the spec has no implementation yet.","truncated":false},"time":{"start":1770187100725,"end":1770187100727}}}}
+{"type":"tool_use","timestamp":1770187100734,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f92310016vUTiBTRHwDM5W","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f5d7a001ahslHtCQnw7J1X","type":"tool","callID":"toolu_013K7yZnRe7rxGp6McUPRv6c","tool":"glob","state":{"status":"completed","input":{"pattern":"**/*.rb"},"output":"No files found","title":"specs","metadata":{"count":0,"truncated":false},"time":{"start":1770187100722,"end":1770187100727}}}}
+{"type":"step_finish","timestamp":1770187100738,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f9238001Bc7W61klSlCgMS","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f5d7a001ahslHtCQnw7J1X","type":"step-finish","reason":"tool-calls","snapshot":"9ff571000c58ef49757c25c596933e95d027b68a","cost":0,"tokens":{"input":5,"output":109,"reasoning":0,"cache":{"read":15463,"write":820}}}}
+{"type":"step_start","timestamp":1770187103298,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f9c3f00174ayQ55QZMnCx1","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f9253001aLp1tmXMfkYWJP","type":"step-start","snapshot":"11b5b96ce076193e7d1845670a5bf54dc1dd710e"}}
+{"type":"tool_use","timestamp":1770187105724,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f9c7100124pI64UBSSh46E","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f9253001aLp1tmXMfkYWJP","type":"tool","callID":"toolu_01FraqehJ4VqbchH6Yg9xCyB","tool":"todowrite","state":{"status":"completed","input":{"todos":[{"id":"1","content":"Design the todo app architecture and data model","status":"completed","priority":"high"},{"id":"2","content":"Implement core Todo and TodoList classes","status":"in_progress","priority":"high"},{"id":"3","content":"Add persistence layer (JSON file storage)","status":"pending","priority":"high"},{"id":"4","content":"Create CLI interface with command handling","status":"pending","priority":"high"},{"id":"5","content":"Add filtering and search capabilities","status":"pending","priority":"medium"},{"id":"6","content":"Implement priority levels and due dates","status":"pending","priority":"medium"},{"id":"7","content":"Add tags and categories","status":"pending","priority":"medium"},{"id":"8","content":"Create pretty output formatting","status":"pending","priority":"medium"},{"id":"9","content":"Write comprehensive tests","status":"pending","priority":"high"},{"id":"10","content":"Add README with usage examples","status":"pending","priority":"low"}]},"output":"[\n  {\n    \"id\": \"1\",\n    \"content\": \"Design the todo app architecture and data model\",\n    \"status\": \"completed\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"2\",\n    \"content\": \"Implement core Todo and TodoList classes\",\n    \"status\": \"in_progress\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"3\",\n    \"content\": \"Add persistence layer (JSON file storage)\",\n    \"status\": \"pending\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"4\",\n    \"content\": \"Create CLI interface with command handling\",\n    \"status\": \"pending\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"5\",\n    \"content\": \"Add filtering and search capabilities\",\n    \"status\": \"pending\",\n    \"priority\": \"medium\"\n  },\n  {\n    \"id\": \"6\",\n    \"content\": \"Implement priority levels and due dates\",\n    \"status\": \"pending\",\n    \"priority\": \"medium\"\n  },\n  {\n    \"id\": \"7\",\n    \"content\": \"Add tags and categories\",\n    \"status\": \"pending\",\n    \"priority\": \"medium\"\n  },\n  {\n    \"id\": \"8\",\n    \"content\": \"Create pretty output formatting\",\n    \"status\": \"pending\",\n    \"priority\": \"medium\"\n  },\n  {\n    \"id\": \"9\",\n    \"content\": \"Write comprehensive tests\",\n    \"status\": \"pending\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"10\",\n    \"content\": \"Add README with usage examples\",\n    \"status\": \"pending\",\n    \"priority\": \"low\"\n  }\n]","title":"9 todos","metadata":{"todos":[{"id":"1","content":"Design the todo app architecture and data model","status":"completed","priority":"high"},{"id":"2","content":"Implement core Todo and TodoList classes","status":"in_progress","priority":"high"},{"id":"3","content":"Add persistence layer (JSON file storage)","status":"pending","priority":"high"},{"id":"4","content":"Create CLI interface with command handling","status":"pending","priority":"high"},{"id":"5","content":"Add filtering and search capabilities","status":"pending","priority":"medium"},{"id":"6","content":"Implement priority levels and due dates","status":"pending","priority":"medium"},{"id":"7","content":"Add tags and categories","status":"pending","priority":"medium"},{"id":"8","content":"Create pretty output formatting","status":"pending","priority":"medium"},{"id":"9","content":"Write comprehensive tests","status":"pending","priority":"high"},{"id":"10","content":"Add README with usage examples","status":"pending","priority":"low"}],"truncated":false},"time":{"start":1770187105711,"end":1770187105720}}}}
+{"type":"step_finish","timestamp":1770187105737,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275fa5ba001LZse64oqhRnWw6","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f9253001aLp1tmXMfkYWJP","type":"step-finish","reason":"tool-calls","snapshot":"0012aee2405832cd50eb58cf61f9d6a06d5ec8d7","cost":0,"tokens":{"input":6,"output":354,"reasoning":0,"cache":{"read":16283,"write":575}}}}
+{"type":"step_start","timestamp":1770187107336,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275fac07001OyYeVzom3wXWKJ","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275fa5de001g6TZgrYArTMYDj","type":"step-start","snapshot":"6a96baea47fc3070e5cca8f349aa76d459448b35"}}
+{"type":"tool_use","timestamp":1770187123469,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275fac08001jiLorarTEUEKFX","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275fa5de001g6TZgrYArTMYDj","type":"tool","callID":"toolu_014EWUsB3p8FPzhZJEW2HWPx","tool":"write","state":{"status":"completed","input":{"filePath":"/home/nathan/src/ralph.rb/specs/lib/todo_item.rb","content":"# frozen_string_literal: true\n\n# Copyright (c) 2025 Nathan Kidd <nathankidd@hey.com>. All rights reserved.\n# SPDX-License-Identifier: Proprietary\n\nrequire 'json'\nrequire 'time'\n\n# Represents a single todo item with full feature support\nclass TodoItem\n  attr_reader :id, :title, :description, :created_at, :updated_at\n  attr_accessor :completed, :priority, :due_date, :tags, :category\n\n  PRIORITIES = { low: 1, medium: 2, high: 3, urgent: 4 }.freeze\n\n  def initialize(title:, description: nil, priority: :medium, due_date: nil, tags: [], category: nil, id: nil)\n    @id = id || generate_id\n    @title = title\n    @description = description\n    @completed = false\n    @priority = priority\n    @due_date = due_date\n    @tags = tags || []\n    @category = category\n    @created_at = Time.now\n    @updated_at = Time.now\n  end\n\n  def complete!\n    if @completed\n      @completed = false\n    else\n      @completed = true\n    end\n    @updated_at = Time.now\n  end\n\n  def completed?\n    @completed\n  end\n\n  def overdue?\n    if @due_date && !@completed\n      Time.parse(@due_date) < Time.now\n    else\n      false\n    end\n  end\n\n  def due_soon?(hours: 24)\n    if @due_date && !@completed\n      due_time = Time.parse(@due_date)\n      due_time > Time.now && due_time < Time.now + (hours * 3600)\n    else\n      false\n    end\n  end\n\n  def priority_value\n    PRIORITIES[@priority] || PRIORITIES[:medium]\n  end\n\n  def add_tag(tag)\n    unless @tags.include?(tag)\n      @tags << tag\n      @updated_at = Time.now\n    end\n  end\n\n  def remove_tag(tag)\n    if @tags.delete(tag)\n      @updated_at = Time.now\n    end\n  end\n\n  def matches_filter?(query: nil, tags: nil, category: nil, completed: nil, priority: nil)\n    if query && !matches_query?(query)\n      false\n    elsif tags && (tags & @tags).empty?\n      false\n    elsif category && @category != category\n      false\n    elsif !completed.nil? && @completed != completed\n      false\n    elsif priority && @priority != priority\n      false\n    else\n      true\n    end\n  end\n\n  def to_h\n    {\n      id: @id,\n      title: @title,\n      description: @description,\n      completed: @completed,\n      priority: @priority,\n      due_date: @due_date,\n      tags: @tags,\n      category: @category,\n      created_at: @created_at.iso8601,\n      updated_at: @updated_at.iso8601\n    }\n  end\n\n  def self.from_h(hash)\n    new(\n      id: hash['id'],\n      title: hash['title'],\n      description: hash['description'],\n      priority: hash['priority']&.to_sym || :medium,\n      due_date: hash['due_date'],\n      tags: hash['tags'] || [],\n      category: hash['category']\n    ).then do |item|\n      item.instance_variable_set(:@completed, hash['completed'] || false)\n      item.instance_variable_set(:@created_at, Time.parse(hash['created_at']))\n      item.instance_variable_set(:@updated_at, Time.parse(hash['updated_at']))\n      item\n    end\n  end\n\n  private\n\n  def generate_id\n    \"#{Time.now.to_i}-#{rand(10000)}\"\n  end\n\n  def matches_query?(query)\n    query_lower = query.downcase\n    if @title.downcase.include?(query_lower)\n      true\n    elsif @description && @description.downcase.include?(query_lower)\n      true\n    elsif @tags.any? { |tag| tag.downcase.include?(query_lower) }\n      true\n    elsif @category && @category.downcase.include?(query_lower)\n      true\n    else\n      false\n    end\n  end\nend\n"},"output":"","title":"specs/lib/todo_item.rb","metadata":{"diagnostics":{"/home/nathan/src/ralph.rb/specs/lib/todo_item.rb":[]},"filepath":"/home/nathan/src/ralph.rb/specs/lib/todo_item.rb","exists":false,"truncated":false},"time":{"start":1770187120035,"end":1770187123465}}}}
+{"type":"step_finish","timestamp":1770187123482,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275feb0b001BNSMKEYbJq0b91","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275fa5de001g6TZgrYArTMYDj","type":"step-finish","reason":"tool-calls","snapshot":"177366b69da91d17a347fe0ad0f65091e4bea58d","cost":0,"tokens":{"input":5,"output":1164,"reasoning":0,"cache":{"read":16858,"write":798}}}}
+{"type":"step_start","timestamp":1770187125160,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275ff1a60017BYnKNMjfD21UA","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275feb31001x6mnGGa2J1HWi5","type":"step-start","snapshot":"9edefc0011373084034390a13e04d98067bc123b"}}

data/specs/loop.md

@@ -0,0 +1,42 @@
+# Loop Specification
+
+What is a ralph loop, and how do we implement one?
+
+## Overview
+
+The essence of a ralph loop is an infinite loop will certain guards to prevent context becoming tainted. If the context becomes too large then then the iteration is cancelled and started again. The work done is not lost, it just means that a fresh context will carry on the work.
+
+This whole technique relies on a way of constantly reminding the agent what it's working on and what it's done. This is simply ensured by a task list. It will be passed the task list as a prompt, and will work until it thinkgs it has completed the task, or it is cancelled by the loop.
+
+## Architecture
+
+A main loop simply runs contonuously to read data from opencode, and check whether the iteration needs cancelling.
+
+An iteration object is created which run the agent, and can be cancelled whenever we like.
+
+In order for the loop to stop once complete, we must instruct the agent to pass back a certain string that we will detect when it thinks it has completed.
+
+### What ends the loop iteration
+- iteration context length
+- iteration duration
+
+### What ends the main loop
+- complete string received
+- max iteration reached
+- loop duration
+
+## Prompts
+Only prompt needed is to explain to return the string once completed, or perhaps to follow the items on the list. The rest can be passed in by the user.
+
+**important** WE MUST INSTRUCT the agent NOT to interact with the user. All questions must be aswered by reading the spec.
+
+## Display Output
+
+We want to see the following:
+- number of iterations
+- current iteration
+- duration
+- tokens consumed
+- over all and per iteration data
+- the output of the agent
+- the input prompt

data/specs/metrics.md

@@ -0,0 +1,51 @@
+# Metrics specification
+
+How will we get essential data such as current context?
+
+## Overview
+
+JSON streaming allows us to do this.
+
+## Architecture
+
+Here's an example JSON stream from opencode. You will read the stream and parse the context from it so that the loop can perform it's checks.
+An Events.rb object will contain classes representing each event we need to parse.
+
+```
+{"type":"step_start","timestamp":1770187082911,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f4c89001ZPPQ0fLyoVyI6R","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f17af001hBx2ZnI5s2T7X6","type":"step-start","snapshot":"b743fc3bfaf58816da3d0e322f5af92274b3318c"}}
+{"type":"text","timestamp":1770187082912,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f4c8b001bqAW435IjTqIWL","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f17af001hBx2ZnI5s2T7X6","type":"text","text":"I'll build you a comprehensive super todo app! Let me create a solid Ruby implementation with all the features you'd want.","time":{"start":1770187082902,"end":1770187082902}}}
+{"type":"tool_use","timestamp":1770187087186,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f4c970017d4K2HeeM44TrY","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f17af001hBx2ZnI5s2T7X6","type":"tool","callID":"toolu_013ZVQg5YJHMYqKHav9rKXUu","tool":"todowrite","state":{"status":"completed","input":{"todos":[{"id":"1","content":"Design the todo app architecture and data model","status":"in_progress","priority":"high"},{"id":"2","content":"Implement core Todo and TodoList classes","status":"pending","priority":"high"},{"id":"3","content":"Add persistence layer (JSON file storage)","status":"pending","priority":"high"},{"id":"4","content":"Create CLI interface with command handling","status":"pending","priority":"high"},{"id":"5","content":"Add filtering and search capabilities","status":"pending","priority":"medium"},{"id":"6","content":"Implement priority levels and due dates","status":"pending","priority":"medium"},{"id":"7","content":"Add tags and categories","status":"pending","priority":"medium"},{"id":"8","content":"Create pretty output formatting","status":"pending","priority":"medium"},{"id":"9","content":"Write comprehensive tests","status":"pending","priority":"high"},{"id":"10","content":"Add README with usage examples","status":"pending","priority":"low"}]},"output":"[\n  {\n    \"id\": \"1\",\n    \"content\": \"Design the todo app architecture and data model\",\n    \"status\": \"in_progress\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"2\",\n    \"content\": \"Implement core Todo and TodoList classes\",\n    \"status\": \"pending\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"3\",\n    \"content\": \"Add persistence layer (JSON file storage)\",\n    \"status\": \"pending\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"4\",\n    \"content\": \"Create CLI interface with command handling\",\n    \"status\": \"pending\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"5\",\n    \"content\": \"Add filtering and search capabilities\",\n    \"status\": \"pending\",\n    \"priority\": \"medium\"\n  },\n  {\n    \"id\": \"6\",\n    \"content\": \"Implement priority levels and due dates\",\n    \"status\": \"pending\",\n    \"priority\": \"medium\"\n  },\n  {\n    \"id\": \"7\",\n    \"content\": \"Add tags and categories\",\n    \"status\": \"pending\",\n    \"priority\": \"medium\"\n  },\n  {\n    \"id\": \"8\",\n    \"content\": \"Create pretty output formatting\",\n    \"status\": \"pending\",\n    \"priority\": \"medium\"\n  },\n  {\n    \"id\": \"9\",\n    \"content\": \"Write comprehensive tests\",\n    \"status\": \"pending\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"10\",\n    \"content\": \"Add README with usage examples\",\n    \"status\": \"pending\",\n    \"priority\": \"low\"\n  }\n]","title":"10 todos","metadata":{"todos":[{"id":"1","content":"Design the todo app architecture and data model","status":"in_progress","priority":"high"},{"id":"2","content":"Implement core Todo and TodoList classes","status":"pending","priority":"high"},{"id":"3","content":"Add persistence layer (JSON file storage)","status":"pending","priority":"high"},{"id":"4","content":"Create CLI interface with command handling","status":"pending","priority":"high"},{"id":"5","content":"Add filtering and search capabilities","status":"pending","priority":"medium"},{"id":"6","content":"Implement priority levels and due dates","status":"pending","priority":"medium"},{"id":"7","content":"Add tags and categories","status":"pending","priority":"medium"},{"id":"8","content":"Create pretty output formatting","status":"pending","priority":"medium"},{"id":"9","content":"Write comprehensive tests","status":"pending","priority":"high"},{"id":"10","content":"Add README with usage examples","status":"pending","priority":"low"}],"truncated":false},"time":{"start":1770187087172,"end":1770187087180}}}}
+{"type":"step_finish","timestamp":1770187087202,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f5d51001K0X6r5is6bSpCF","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f17af001hBx2ZnI5s2T7X6","type":"step-finish","reason":"tool-calls","snapshot":"a57194ef5a651225fcd30a8c1693512e5ac64d59","cost":0,"tokens":{"input":2,"output":392,"reasoning":0,"cache":{"read":0,"write":15463}}}}
+{"type":"step_start","timestamp":1770187100723,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f9230001va5bdY1KhjxQG0","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f5d7a001ahslHtCQnw7J1X","type":"step-start","snapshot":"cdd7b1abdd3f43bd9efb116cffba98955ba57a2e"}}
+{"type":"tool_use","timestamp":1770187100734,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f9234001Uu930gEHD2BlmN","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f5d7a001ahslHtCQnw7J1X","type":"tool","callID":"toolu_01EYZZEC8oyTLrULZrUsUEx2","tool":"read","state":{"status":"completed","input":{"filePath":"/home/nathan/src/ralph.rb/specs/README.md"},"output":"<file>\n00001| <!--\n00002|  Copyright (c) 2025 Nathan Kidd <nathankidd@hey.com>. All rights reserved.\n00003|  SPDX-License-Identifier: Proprietary\n00004| -->\n00005| \n00006| <!--\n00007|   HOW TO MAINTAIN THIS FILE\n00008| \n00009|   This is the index of all design specifications for Ralph.rb.\n00010|   Each row links a spec document to its implementation code and a short purpose summary.\n00011| \n00012|   When adding a new spec:\n00013|   1. Create the markdown file in this directory (specs/)\n00014|   2. Add a row to the appropriate table section below\n00015|   3. Link the spec file, the code path it describes, and a brief purpose\n00016| \n00017|   Table format:\n00018|     | [spec-name.md](./spec-name.md) | [path/to/code](../path/to/code) | Short description |\n00019| \n00020|   Use \"—\" in the Code column if the spec has no implementation yet.\n00021|   Group specs under heading sections by domain area.\n00022| -->\n00023| \n00024| # Ralph.rb Specifications\n00025| \n00026| Design documentation for Ralph.rb, a Ruby CLI that runs iterative AI development loops.\n00027| \n00028| ## Core\n00029| \n00030| | Spec | Code | Purpose |\n00031| |------|------|---------|\n00032| \n\n(End of file - total 32 lines)\n</file>","title":"specs/README.md","metadata":{"preview":"<!--\n Copyright (c) 2025 Nathan Kidd <nathankidd@hey.com>. All rights reserved.\n SPDX-License-Identifier: Proprietary\n-->\n\n<!--\n  HOW TO MAINTAIN THIS FILE\n\n  This is the index of all design specifications for Ralph.rb.\n  Each row links a spec document to its implementation code and a short purpose summary.\n\n  When adding a new spec:\n  1. Create the markdown file in this directory (specs/)\n  2. Add a row to the appropriate table section below\n  3. Link the spec file, the code path it describes, and a brief purpose\n\n  Table format:\n    | [spec-name.md](./spec-name.md) | [path/to/code](../path/to/code) | Short description |\n\n  Use \"—\" in the Code column if the spec has no implementation yet.","truncated":false},"time":{"start":1770187100725,"end":1770187100727}}}}
+{"type":"tool_use","timestamp":1770187100734,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f92310016vUTiBTRHwDM5W","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f5d7a001ahslHtCQnw7J1X","type":"tool","callID":"toolu_013K7yZnRe7rxGp6McUPRv6c","tool":"glob","state":{"status":"completed","input":{"pattern":"**/*.rb"},"output":"No files found","title":"specs","metadata":{"count":0,"truncated":false},"time":{"start":1770187100722,"end":1770187100727}}}}
+{"type":"step_finish","timestamp":1770187100738,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f9238001Bc7W61klSlCgMS","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f5d7a001ahslHtCQnw7J1X","type":"step-finish","reason":"tool-calls","snapshot":"9ff571000c58ef49757c25c596933e95d027b68a","cost":0,"tokens":{"input":5,"output":109,"reasoning":0,"cache":{"read":15463,"write":820}}}}
+{"type":"step_start","timestamp":1770187103298,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f9c3f00174ayQ55QZMnCx1","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f9253001aLp1tmXMfkYWJP","type":"step-start","snapshot":"11b5b96ce076193e7d1845670a5bf54dc1dd710e"}}
+{"type":"tool_use","timestamp":1770187105724,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275f9c7100124pI64UBSSh46E","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f9253001aLp1tmXMfkYWJP","type":"tool","callID":"toolu_01FraqehJ4VqbchH6Yg9xCyB","tool":"todowrite","state":{"status":"completed","input":{"todos":[{"id":"1","content":"Design the todo app architecture and data model","status":"completed","priority":"high"},{"id":"2","content":"Implement core Todo and TodoList classes","status":"in_progress","priority":"high"},{"id":"3","content":"Add persistence layer (JSON file storage)","status":"pending","priority":"high"},{"id":"4","content":"Create CLI interface with command handling","status":"pending","priority":"high"},{"id":"5","content":"Add filtering and search capabilities","status":"pending","priority":"medium"},{"id":"6","content":"Implement priority levels and due dates","status":"pending","priority":"medium"},{"id":"7","content":"Add tags and categories","status":"pending","priority":"medium"},{"id":"8","content":"Create pretty output formatting","status":"pending","priority":"medium"},{"id":"9","content":"Write comprehensive tests","status":"pending","priority":"high"},{"id":"10","content":"Add README with usage examples","status":"pending","priority":"low"}]},"output":"[\n  {\n    \"id\": \"1\",\n    \"content\": \"Design the todo app architecture and data model\",\n    \"status\": \"completed\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"2\",\n    \"content\": \"Implement core Todo and TodoList classes\",\n    \"status\": \"in_progress\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"3\",\n    \"content\": \"Add persistence layer (JSON file storage)\",\n    \"status\": \"pending\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"4\",\n    \"content\": \"Create CLI interface with command handling\",\n    \"status\": \"pending\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"5\",\n    \"content\": \"Add filtering and search capabilities\",\n    \"status\": \"pending\",\n    \"priority\": \"medium\"\n  },\n  {\n    \"id\": \"6\",\n    \"content\": \"Implement priority levels and due dates\",\n    \"status\": \"pending\",\n    \"priority\": \"medium\"\n  },\n  {\n    \"id\": \"7\",\n    \"content\": \"Add tags and categories\",\n    \"status\": \"pending\",\n    \"priority\": \"medium\"\n  },\n  {\n    \"id\": \"8\",\n    \"content\": \"Create pretty output formatting\",\n    \"status\": \"pending\",\n    \"priority\": \"medium\"\n  },\n  {\n    \"id\": \"9\",\n    \"content\": \"Write comprehensive tests\",\n    \"status\": \"pending\",\n    \"priority\": \"high\"\n  },\n  {\n    \"id\": \"10\",\n    \"content\": \"Add README with usage examples\",\n    \"status\": \"pending\",\n    \"priority\": \"low\"\n  }\n]","title":"9 todos","metadata":{"todos":[{"id":"1","content":"Design the todo app architecture and data model","status":"completed","priority":"high"},{"id":"2","content":"Implement core Todo and TodoList classes","status":"in_progress","priority":"high"},{"id":"3","content":"Add persistence layer (JSON file storage)","status":"pending","priority":"high"},{"id":"4","content":"Create CLI interface with command handling","status":"pending","priority":"high"},{"id":"5","content":"Add filtering and search capabilities","status":"pending","priority":"medium"},{"id":"6","content":"Implement priority levels and due dates","status":"pending","priority":"medium"},{"id":"7","content":"Add tags and categories","status":"pending","priority":"medium"},{"id":"8","content":"Create pretty output formatting","status":"pending","priority":"medium"},{"id":"9","content":"Write comprehensive tests","status":"pending","priority":"high"},{"id":"10","content":"Add README with usage examples","status":"pending","priority":"low"}],"truncated":false},"time":{"start":1770187105711,"end":1770187105720}}}}
+{"type":"step_finish","timestamp":1770187105737,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275fa5ba001LZse64oqhRnWw6","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275f9253001aLp1tmXMfkYWJP","type":"step-finish","reason":"tool-calls","snapshot":"0012aee2405832cd50eb58cf61f9d6a06d5ec8d7","cost":0,"tokens":{"input":6,"output":354,"reasoning":0,"cache":{"read":16283,"write":575}}}}
+{"type":"step_start","timestamp":1770187107336,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275fac07001OyYeVzom3wXWKJ","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275fa5de001g6TZgrYArTMYDj","type":"step-start","snapshot":"6a96baea47fc3070e5cca8f349aa76d459448b35"}}
+{"type":"tool_use","timestamp":1770187123469,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275fac08001jiLorarTEUEKFX","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275fa5de001g6TZgrYArTMYDj","type":"tool","callID":"toolu_014EWUsB3p8FPzhZJEW2HWPx","tool":"write","state":{"status":"completed","input":{"filePath":"/home/nathan/src/ralph.rb/specs/lib/todo_item.rb","content":"# frozen_string_literal: true\n\n# Copyright (c) 2025 Nathan Kidd <nathankidd@hey.com>. All rights reserved.\n# SPDX-License-Identifier: Proprietary\n\nrequire 'json'\nrequire 'time'\n\n# Represents a single todo item with full feature support\nclass TodoItem\n  attr_reader :id, :title, :description, :created_at, :updated_at\n  attr_accessor :completed, :priority, :due_date, :tags, :category\n\n  PRIORITIES = { low: 1, medium: 2, high: 3, urgent: 4 }.freeze\n\n  def initialize(title:, description: nil, priority: :medium, due_date: nil, tags: [], category: nil, id: nil)\n    @id = id || generate_id\n    @title = title\n    @description = description\n    @completed = false\n    @priority = priority\n    @due_date = due_date\n    @tags = tags || []\n    @category = category\n    @created_at = Time.now\n    @updated_at = Time.now\n  end\n\n  def complete!\n    if @completed\n      @completed = false\n    else\n      @completed = true\n    end\n    @updated_at = Time.now\n  end\n\n  def completed?\n    @completed\n  end\n\n  def overdue?\n    if @due_date && !@completed\n      Time.parse(@due_date) < Time.now\n    else\n      false\n    end\n  end\n\n  def due_soon?(hours: 24)\n    if @due_date && !@completed\n      due_time = Time.parse(@due_date)\n      due_time > Time.now && due_time < Time.now + (hours * 3600)\n    else\n      false\n    end\n  end\n\n  def priority_value\n    PRIORITIES[@priority] || PRIORITIES[:medium]\n  end\n\n  def add_tag(tag)\n    unless @tags.include?(tag)\n      @tags << tag\n      @updated_at = Time.now\n    end\n  end\n\n  def remove_tag(tag)\n    if @tags.delete(tag)\n      @updated_at = Time.now\n    end\n  end\n\n  def matches_filter?(query: nil, tags: nil, category: nil, completed: nil, priority: nil)\n    if query && !matches_query?(query)\n      false\n    elsif tags && (tags & @tags).empty?\n      false\n    elsif category && @category != category\n      false\n    elsif !completed.nil? && @completed != completed\n      false\n    elsif priority && @priority != priority\n      false\n    else\n      true\n    end\n  end\n\n  def to_h\n    {\n      id: @id,\n      title: @title,\n      description: @description,\n      completed: @completed,\n      priority: @priority,\n      due_date: @due_date,\n      tags: @tags,\n      category: @category,\n      created_at: @created_at.iso8601,\n      updated_at: @updated_at.iso8601\n    }\n  end\n\n  def self.from_h(hash)\n    new(\n      id: hash['id'],\n      title: hash['title'],\n      description: hash['description'],\n      priority: hash['priority']&.to_sym || :medium,\n      due_date: hash['due_date'],\n      tags: hash['tags'] || [],\n      category: hash['category']\n    ).then do |item|\n      item.instance_variable_set(:@completed, hash['completed'] || false)\n      item.instance_variable_set(:@created_at, Time.parse(hash['created_at']))\n      item.instance_variable_set(:@updated_at, Time.parse(hash['updated_at']))\n      item\n    end\n  end\n\n  private\n\n  def generate_id\n    \"#{Time.now.to_i}-#{rand(10000)}\"\n  end\n\n  def matches_query?(query)\n    query_lower = query.downcase\n    if @title.downcase.include?(query_lower)\n      true\n    elsif @description && @description.downcase.include?(query_lower)\n      true\n    elsif @tags.any? { |tag| tag.downcase.include?(query_lower) }\n      true\n    elsif @category && @category.downcase.include?(query_lower)\n      true\n    else\n      false\n    end\n  end\nend\n"},"output":"","title":"specs/lib/todo_item.rb","metadata":{"diagnostics":{"/home/nathan/src/ralph.rb/specs/lib/todo_item.rb":[]},"filepath":"/home/nathan/src/ralph.rb/specs/lib/todo_item.rb","exists":false,"truncated":false},"time":{"start":1770187120035,"end":1770187123465}}}}
+{"type":"step_finish","timestamp":1770187123482,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275feb0b001BNSMKEYbJq0b91","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275fa5de001g6TZgrYArTMYDj","type":"step-finish","reason":"tool-calls","snapshot":"177366b69da91d17a347fe0ad0f65091e4bea58d","cost":0,"tokens":{"input":5,"output":1164,"reasoning":0,"cache":{"read":16858,"write":798}}}}
+{"type":"step_start","timestamp":1770187125160,"sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","part":{"id":"prt_c275ff1a60017BYnKNMjfD21UA","sessionID":"ses_3d8a0e8abffesEdbo6QsvtRrNS","messageID":"msg_c275feb31001x6mnGGa2J1HWi5","type":"step-start","snapshot":"9edefc0011373084034390a13e04d98067bc123b"}}
+```
+
+## calculation
+
+The context size lives in the `step_finish` events, in the `tokens` field. The total input context for any step is:
+
+```
+context = input + cache.read + cache.write
+```
+
+Walking through your log:
+
+| Step | input | cache.read | cache.write | **Total Context** |
+|------|-------|------------|-------------|-------------------|
+| 1 | 2 | 0 | 15,463 | **15,465** |
+| 2 | 5 | 15,463 | 820 | **16,288** |
+| 3 | 6 | 16,283 | 575 | **16,864** |
+| 4 | 5 | 16,858 | 798 | **17,661** |
+
+The pattern: each step's `cache.read` ≈ previous step's `cache.read + cache.write`, meaning the previously-seen context gets cached. The `cache.write` is the new tokens added that step (tool results, assistant output). `input` is the tiny uncacheable portion (likely the few tokens at a cache boundary).
+
+So to get the current context window usage at any point, sum all three input token fields from the most recent `step_finish`. To track growth over time, chart that sum across steps — you can see context growing ~400-1200 tokens per step here as tool results accumulate.