osgrep proposal and idle detection for cli injection#127
Merged
khaliqgant merged 8 commits intomainfrom Jan 10, 2026
Merged
Conversation
Detailed technical proposal for integrating llm-tldr code analysis with agent-relay via direct Unix socket communication. Key design decisions: - Service as first-class entity type in relay protocol - TldrBridge component for protocol translation - Request-response pattern with timeouts - Agent-facing ->relay:tldr syntax - Continuity integration for startup context enrichment - Caching layer with file watcher invalidation Includes architecture diagrams, implementation phases, and performance targets (<150ms round-trip).
Addresses the ecosystem mismatch problem: - agent-relay: TypeScript/Node.js/npm - llm-tldr: Python/pip with 2GB ML dependencies Analyzes 6 options with pros/cons: 1. User responsibility (manual install) 2. Subprocess management (pip from Node) 3. Docker sidecar (recommended for prod) 4. npm wrapper package (fragile) 5. Cloud-hosted service (adds latency) 6. Native TypeScript port (long-term) Proposes tiered strategy: - Tier 1: Detection only (MVP) - Tier 2: Docker integration - Tier 3: Managed installation - Tier 4: Evaluate native port
osgrep Integration (docs/proposals/OSGREP-INTEGRATION.md): - TypeScript-native semantic code search via HTTP API - 150MB footprint vs llm-tldr's 2GB Python stack - ->relay:code pattern for agent queries - Startup context injection for auto-discovery - Defers structural analysis pending agent feedback Agent Retrospectives (docs/AGENT-RETROSPECTIVE-QUESTIONS.md): - Question bank for post-task agent reviews - Specific questions to validate call graph need - Decision criteria: >50% demand → build, <20% → defer - Aggregation patterns for weekly tracking Lead Agent Update (.claude/agents/lead.md): - Added retrospective section with quick retro template - Key questions table for tracking tooling needs - Links to full question bank
Addresses unreliable startup context injection where agents often ignore or never receive continuity data. Key problems identified: - Arbitrary 3s delay doesn't match agent readiness - Idle check (1500ms) never satisfied during agent generation - No feedback loop to confirm receipt - Silent failure leaves agents unaware Proposed solution: 1. Readiness detection - wait for actual prompt/ready signal 2. Priority queue with retry/backoff strategy 3. Acknowledgment loop - agent confirms receipt 4. File fallback - write to CLAUDE.md if injection fails 5. Notification fallback - tell agent context is available Includes metrics, testing strategy, and migration path.
Replaces pattern-based readiness detection with hybrid approach:
1. Process state inspection (Linux):
- Check /proc/{pid}/stat for sleep state
- Check /proc/{pid}/wchan for input wait channels
- 95% confidence when process blocked on read
2. Output silence analysis (cross-platform fallback):
- Track time since last output
- Confidence scales with silence duration
3. Natural ending detection:
- Detect complete thoughts vs mid-sentence
- Check for sentence endings, code blocks, prompts
Combines signals with confidence scoring. Works across all CLI
types (Claude, Codex, Gemini, Aider, Droid, etc.) without
requiring CLI-specific pattern matching.
Implements universal idle detection for all CLI-based agents using a
hybrid approach:
1. Process state inspection via /proc/{pid}/stat and /proc/{pid}/wchan
on Linux (95% confidence) - detects when process is waiting for input
2. Output silence analysis (cross-platform, 60-80% confidence) - tracks
time since last output
3. Natural ending detection (heuristic, 60% confidence) - checks if
output ends with prompt/sentence vs mid-thought
This replaces the simple time-based idle check in TmuxWrapper with
multi-signal detection that works across Claude, Codex, Gemini, Aider,
and any other CLI tool.
Key components:
- src/wrapper/idle-detector.ts: UniversalIdleDetector class with
process state inspection and output analysis
- getTmuxPanePid(): Helper to get process PID from tmux session
- Integration with TmuxWrapper.checkForInjectionOpportunity()
The detector is initialized with the tmux pane PID on session start
and receives output chunks during polling for accurate idle detection.
Addresses context injection timing issues by providing reliable
detection of when agents are ready for input.
Previously, the UniversalIdleDetector was added separately to both TmuxWrapper and PtyWrapper, violating the DRY principle. This refactors the implementation to follow proper inheritance patterns: Changes: - Move idleDetector property and initialization to BaseWrapper - Add protected helper methods: setIdleDetectorPid(), feedIdleDetectorOutput(), checkIdleForInjection(), waitForIdleState() - Update TmuxWrapper and PtyWrapper to use inherited methods - Remove duplicate idleDetector declarations from subclasses - Add idleBeforeInjectMs and idleConfidenceThreshold to BaseWrapperConfig Also adds .claude/rules/wrapper-inheritance.md to enforce this pattern for future development - any shared functionality between wrappers should be added to BaseWrapper first. This ensures consistent behavior across all wrapper types and prevents code divergence.
khaliqgant
changed the title
Spawned agents were missing their initial task because the wrappers used fixed delays (2-3 seconds) instead of detecting when the CLI was actually ready for input. Changes: - PtyWrapper: Replace 2-second setTimeout with waitForAgentReady() that uses idle detection (waitForIdleState) - TmuxWrapper: Replace 3-second setTimeout with waitForAgentReady() that uses idle detection The new approach: 1. Waits minimum 500ms for CLI process to start 2. Uses UniversalIdleDetector to detect when CLI is idle 3. Times out after 10 seconds with fallback behavior This fixes the issue where spawn tasks were sent before the agent was ready to receive them, causing messages to be lost.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implementation
Universal Idle Detection
Hybrid detection approach that works across Claude, Codex, Gemini, Aider, and any CLI:
/proc/{pid}/stat(Linux, 95% confidence)Proper Inheritance
BaseWrapper, not duplicated in subclassessetIdleDetectorPid(),feedIdleDetectorOutput(),checkIdleForInjection().claude/rules/wrapper-inheritance.mdto enforce patternProposals
Test plan