Problem Description

When an iteration completes, Ralph TUI automatically appends an entry to .ralph-tui/progress.md via the appendProgress() function. This causes two significant issues:

Issue 1: Duplicate Entries

The agent (following the template's workflow instructions) already writes a well-formatted progress entry. Then Ralph TUI appends a second entry for the same iteration, resulting in duplicates:

## ✓ Iteration 5 - US-005: Android Unit Test Foundation

**What was implemented:**
- Added test dependencies to build.gradle
- Created test files with 29 test cases
[... detailed, well-formatted entry from agent ...]

---
## ✓ Iteration 5 - US-005: Android Unit Test Foundation
*2026-01-24T21:41:15.148Z (262s)*

**Status:** Completed

**Notes:**
icxAL41rvZ","type":"message","role":"assistant","content":[{"type":"text"...

Issue 2: Gibberish in Auto-Appended Notes

The extractCompletionNotes() function captures the last ~500 characters before <promise>COMPLETE</promise>. Since the agent's output is JSON-formatted internally, this often captures:

• Message IDs: icxAL41rvZ
• JSON fragments: ","type":"message","role":"assistant","content":[
• Partial text from agent responses

This results in completely unusable "Notes" sections that pollute the progress file.

Impact

1. Wasted tokens: Agents read progress.md and process gibberish entries
2. Confusing history: Duplicate entries for each iteration
3. No deduplication: The append-only design doesn't check for existing entries
4. Reduced reliability: Future iterations may misinterpret malformed entries

Proposed Solutions

Option A: Config flag to disable auto-append (Preferred)

Add a configuration option in config.toml:

[progress]
autoAppend = false  # Disable Ralph TUI auto-append, let agent manage progress.md

This gives users control over whether Ralph TUI should manage progress entries or leave it to the agent.

Option B: Deduplication before append

Before appending, check if an entry for the current iteration already exists:

// In appendProgress()
const existingPattern = new RegExp(`## [✓✗] Iteration ${iterationNum}`, 'g');
if (existingPattern.test(existingContent)) {
  // Entry already exists, skip auto-append
  return;
}

Option C: Fix note extraction

Improve extractCompletionNotes() to filter JSON artifacts more aggressively:

function extractCompletionNotes(output: string): string {
  // Filter out JSON fragments, message IDs, etc.
  const jsonPatterns = [
    /","type":"[^"]+"/g,
    /"role":"[^"]+"/g,
    /[a-zA-Z0-9]{10,}",/g,  // Message ID fragments
    /"content":\[/g,
  ];
  // ... apply filters
}

Environment

• Ralph TUI version: Latest
• Agent: Claude (claude-opus-4-5)
• Tracker: JSON

Workaround

Currently instructing the agent via template to clean up gibberish entries:

### Phase 3: Documentation
7. **Clean up progress.md** - Remove any malformed entries (JSON fragments, gibberish in Notes sections, duplicate iteration headers)

This works but is inefficient and error-prone.

Related

• The recentProgress template variable extracts last 5 iterations, but agents also read the full file per workflow instructions, making recentProgress redundant
• File truncation (50KB limit) is separate from the 5-iteration prompt limit, causing confusion

Thank you for considering this improvement!