172 lines
11 KiB
Markdown
172 lines
11 KiB
Markdown
# Project Research Summary
|
|
|
|
**Project:** gsd-openclaw (OpenClaw to GSD Bridge)
|
|
**Domain:** tmux-Claude CLI integration + OpenClaw skill bridging
|
|
**Researched:** 2026-03-10
|
|
**Confidence:** HIGH
|
|
|
|
## Executive Summary
|
|
|
|
The gsd-openclaw skill is a bridge layer connecting OpenClaw's multi-channel messaging system to GSD's Claude CLI-based project management workflow. Experts in this domain build such integrations using a **session-orchestrator-bridge pattern**: tmux provides persistent terminal sessions for Claude CLI context, libtmux offers a clean Python API for programmatic control, and a skill layer handles command routing and state management.
|
|
|
|
The recommended approach is a pure bridge pattern with zero modifications to GSD core. All interaction flows through tmux sessions running Claude CLI, with the skill layer translating chat messages to GSD slash commands and capturing responses. The architecture uses session-per-project isolation for context purity and security, async response handling for channel timeout constraints, and JSON-based state checkpointing for recovery from interruptions.
|
|
|
|
Key risks include tmux server crashes (can destroy all sessions), prompt injection vulnerabilities (malicious user messages could trick Claude), and session state corruption on force-terminate. Mitigations include separate tmux servers per user/project group, input sanitization, and atomic writes with graceful shutdown procedures.
|
|
|
|
## Key Findings
|
|
|
|
### Recommended Stack
|
|
|
|
Python 3.9+ with libtmux 0.46.2 for tmux integration provides the foundation. Claude CLI (official Anthropic tool) runs inside tmux sessions for persistent conversational context. JSON files handle state persistence following the dev-workflow pattern. OpenClaw's skill framework provides the integration point via SKILL.md frontmatter.
|
|
|
|
**Core technologies:**
|
|
- **libtmux 0.46.2:** Python ORM for tmux - type-safe API, active maintenance, 10+ years history
|
|
- **Claude CLI:** Official Anthropic agentic coding tool - supports interactive mode, session continuation, JSON output
|
|
- **tmux 1.8+:** Terminal multiplexer - industry standard for persistent sessions
|
|
- **Python 3.9+:** Core language - stdlib modules (pathlib, json, argparse) sufficient for MVP
|
|
- **JSON state files:** Persistence layer - human-readable, matches OpenClaw patterns
|
|
|
|
**Rejected alternatives:** pexpect (unnecessary abstraction), screen (less Python support), SQLite (overkill), asyncio (inherently synchronous domain), npm installation for Claude CLI (deprecated).
|
|
|
|
### Expected Features
|
|
|
|
**Must have (table stakes):**
|
|
- **Session persistence** - Claude CLI conversations span hours/days; tmux + JSON state provides this
|
|
- **Command bridging** - Parse /gsd:* commands, forward to Claude CLI, return responses
|
|
- **SKILL.md frontmatter** - AgentSkills spec compliance; OpenClaw won't load skill without it
|
|
- **Workspace isolation** - Per-project tmux sessions and directory structure
|
|
- **State recovery** - JSON state files enable recovery from network drops, restarts
|
|
- **Error handling** - Failures reported clearly through chat channel
|
|
- **Multi-channel support** - OpenClaw handles channel abstraction; skill is channel-agnostic
|
|
|
|
**Should have (differentiators):**
|
|
- **Proactive notifications** - Push updates when long-running tasks complete
|
|
- **Interactive approval flow** - Request user confirmation for risky operations
|
|
- **Intelligent retry** - Auto-retry failed operations with backoff (dev-workflow: 3 retries)
|
|
- **Progress snapshots** - Periodic progress reports during long operations
|
|
- **Rich output formatting** - Channel-adaptive markdown rendering
|
|
|
|
**Defer (v2+):**
|
|
- **Multi-agent coordination** - Complex; dev-workflow shows it's achievable but not MVP
|
|
- **Session branching** - Fork session state for "what if" exploration
|
|
- **Session handoff** - Transfer session between channels (cross-channel identity complex)
|
|
- **Intelligent context management** - Auto-summarize long sessions to keep context usable
|
|
|
|
### Architecture Approach
|
|
|
|
The skill acts as a bridge between OpenClaw's WebSocket control plane and GSD's Claude CLI sessions running in tmux. A session-orchestrator-bridge pattern separates concerns: SKILL.md handles trigger matching, orchestrator.py routes commands and formats responses, tmux_session_manager.py manages session lifecycle, and state_manager.py handles persistence.
|
|
|
|
**Major components:**
|
|
1. **SKILL.md** - Trigger pattern matching (/gsd:*, project management keywords), routes to orchestrator
|
|
2. **orchestrator.py** - Command routing, user auth, state coordination, response formatting
|
|
3. **tmux_session_manager.py** - Create/destroy tmux sessions per user-project, send commands, capture output
|
|
4. **state_manager.py** - Persistent JSON storage, project workspace tracking, user session mapping
|
|
5. **response_formatter.py** - Channel-adaptive formatting (compact for mobile, rich for Slack/Discord)
|
|
|
|
**Key patterns:**
|
|
- Session-per-project isolation prevents context pollution
|
|
- Async response handling with callbacks for channel timeout constraints
|
|
- State checkpointing enables recovery from interruption
|
|
- Channel-adaptive formatting for different messaging platforms
|
|
|
|
### Critical Pitfalls
|
|
|
|
1. **tmux Server Crash Destroys All Sessions** - Use separate tmux sockets/servers per user/project, implement session state serialization, monitor server health
|
|
2. **Prompt Injection via User Messages** - Sanitize all input, use clear system prompts, implement command allowlisting, run in sandboxed environments
|
|
3. **Control Mode Flow Control Desynchronization** - Implement robust %begin/%end parsing, handle async notifications separately, use unique command tokens
|
|
4. **Session State Corruption on Force-Terminate** - Use graceful shutdown (SIGTERM first), atomic writes (temp file then rename), create snapshots before destructive ops
|
|
5. **TERM Environment Mismatch** - Explicitly set TERM=xterm-256color, verify terminfo entries exist
|
|
|
|
## Implications for Roadmap
|
|
|
|
Based on research, suggested phase structure:
|
|
|
|
### Phase 1: Core Infrastructure
|
|
**Rationale:** Foundation layer required by all other components. state_manager.py has no dependencies and is needed by orchestrator. tmux_session_manager depends on state_manager for workspace paths.
|
|
**Delivers:** Persistent state management, tmux session lifecycle, TERM configuration
|
|
**Addresses:** Session persistence, workspace isolation, error handling (table stakes)
|
|
**Avoids:** TERM mismatch (#1), tmux server crash (#2), zombie sessions (#9), state corruption (#5)
|
|
|
|
### Phase 2: Integration Layer
|
|
**Rationale:** Standalone components needed before orchestration. response_formatter and prompts are static/configurable with no runtime dependencies.
|
|
**Delivers:** Channel-adaptive formatting, prompt templates for context recovery and error handling
|
|
**Uses:** Python stdlib, OpenClaw channel abstraction
|
|
**Implements:** Multi-channel support pattern
|
|
|
|
### Phase 3: Orchestration
|
|
**Rationale:** Orchestrator depends on all infrastructure components. SKILL.md defines triggers that invoke orchestrator methods.
|
|
**Delivers:** Command routing, user authentication, bidirectional command bridging
|
|
**Addresses:** Command bridging, SKILL.md frontmatter (table stakes)
|
|
**Implements:** orchestrator.py component, async response handling pattern
|
|
**Avoids:** Control mode desync (#3), prompt injection (#4)
|
|
|
|
### Phase 4: GSD Integration
|
|
**Rationale:** Full GSD command bridging requires stable orchestrator and session management. Approval flows depend on bidirectional I/O.
|
|
**Delivers:** All GSD slash commands bridged, interactive approval flows, progress reporting
|
|
**Addresses:** Interactive approval flow (differentiator), progress snapshots (differentiator)
|
|
**Implements:** State file integration with GSD's .planning/ structure
|
|
|
|
### Phase 5: Polish & Notifications
|
|
**Rationale:** Proactive features require stable foundation. Notification callbacks depend on async monitoring infrastructure from Phase 3.
|
|
**Delivers:** Proactive notifications, intelligent retry, rich output formatting refinement
|
|
**Addresses:** Proactive notifications (differentiator), intelligent retry (differentiator), rich formatting (differentiator)
|
|
**Avoids:** Missing error context (#12), Claude CLI version incompatibility (#13)
|
|
|
|
### Phase Ordering Rationale
|
|
|
|
- **Dependencies first:** state_manager -> tmux_session_manager -> orchestrator -> SKILL.md follows natural dependency chain
|
|
- **Grouping by concern:** Infrastructure (1-2), Orchestration (3), Integration (4), Polish (5) groups related work
|
|
- **Risk mitigation early:** TERM settings, graceful shutdown, separate servers addressed in Phase 1 prevents cascading issues
|
|
- **Pure bridge enforced:** Architecture explicitly avoids GSD modifications - all interaction via tmux + slash commands
|
|
|
|
### Research Flags
|
|
|
|
Phases likely needing deeper research during planning:
|
|
- **Phase 4:** GSD integration specifics - exact slash command outputs, approval flow prompts, .planning/ structure details
|
|
- **Phase 5:** Notification delivery patterns - OpenClaw push notification API, callback mechanisms
|
|
|
|
Phases with standard patterns (skip research-phase):
|
|
- **Phase 1:** Well-documented libtmux patterns, dev-workflow reference for state_manager
|
|
- **Phase 2:** Standard Python formatting, prompts are static content
|
|
- **Phase 3:** Orchestrator pattern from dev-workflow, async patterns well-established
|
|
|
|
## Confidence Assessment
|
|
|
|
| Area | Confidence | Notes |
|
|
|------|------------|-------|
|
|
| Stack | HIGH | libtmux v0.46.2 verified PyPI (May 2025), Claude CLI official docs, dev-workflow reference |
|
|
| Features | HIGH | OpenClaw docs comprehensive, dev-workflow shows patterns, clear table stakes/differentiators |
|
|
| Architecture | HIGH | Direct reference from dev-workflow, official OpenClaw docs, clear component boundaries |
|
|
| Pitfalls | MEDIUM | Official tmux/OpenClaw docs, but some extrapolation on specific failure modes |
|
|
|
|
**Overall confidence:** HIGH
|
|
|
|
### Gaps to Address
|
|
|
|
- **Scalability estimates:** Theoretical 100-user estimates need real-world validation; consider session pooling/LRU eviction if scaling beyond MVP
|
|
- **Claude CLI specifics:** Exact output formats for GSD commands need testing during Phase 4; JSON output mode behavior with interactive prompts unclear
|
|
- **OpenClaw async callbacks:** Notification push mechanism needs validation against OpenClaw API during Phase 5
|
|
|
|
## Sources
|
|
|
|
### Primary (HIGH confidence)
|
|
- libtmux PyPI: https://pypi.org/project/libtmux/ (v0.46.2, May 26, 2025)
|
|
- Claude Code Overview: https://docs.anthropic.com/en/docs/claude-code/overview
|
|
- Claude Code CLI Usage: https://docs.anthropic.com/en/docs/claude-code/cli-usage
|
|
- OpenClaw Skills docs: https://docs.openclaw.ai/skills
|
|
- OpenClaw Multi-agent docs: https://docs.openclaw.ai/multi-agent
|
|
- dev-workflow skill reference: /home/starmen1265/.openclaw/skills/dev-workflow/
|
|
|
|
### Secondary (MEDIUM confidence)
|
|
- tmux FAQ: https://github.com/tmux/tmux/wiki/FAQ - TERM settings, server crashes
|
|
- tmux Control Mode docs: https://github.com/tmux/tmux/wiki/Control-Mode - Programmatic control protocol
|
|
- OpenClaw Security docs: https://openclaw.ai/security - Prompt injection, DM policies
|
|
|
|
### Tertiary (contextual)
|
|
- libtmux GitHub: https://github.com/tmux-python/libtmux
|
|
- Claude Code GitHub: https://github.com/anthropics/claude-code
|
|
|
|
---
|
|
*Research completed: 2026-03-10*
|
|
*Ready for roadmap: yes*
|