# Technology Stack

**Project:** gsd-openclaw (OpenClaw to GSD Bridge)
**Researched:** 2026-03-10

## Recommended Stack

### Session Management (tmux Integration)

| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
| libtmux | 0.46.2 (May 2025) | Python ORM for tmux | Official Python wrapper with ORM-style API. Provides `pane.send_keys()` for input, `pane.cmd('capture-pane', '-p')` for output capture. Supports session/window/pane object model. Active maintenance (last release May 26, 2025). |
| tmux | 1.8+ | Terminal multiplexer | Industry standard for persistent terminal sessions. Required by libtmux. Enables Claude CLI context persistence across network disconnections. |

**Confidence:** HIGH - libtmux v0.46.2 verified from PyPI (May 2025), actively maintained with 10+ years of development history.

### Claude CLI Integration

| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
| Claude Code CLI | Latest (via npm/@anthropic-ai/claude-code) | Agentic coding tool | Official Anthropic CLI tool. Supports interactive mode (`claude`), one-shot mode (`claude -p "query"`), session continuation (`-c`), and session resume by ID (`-r "session-id"`). JSON output format for programmatic use. |

**Key CLI patterns for bridge:**
```bash
# Interactive mode (for persistent sessions)
claude

# One-shot with JSON output (for programmatic calls)
claude -p "query" --output-format json

# Continue previous conversation
claude -c -p "continue this task"

# Resume specific session
claude -r "abc123" "Finish this PR"
```

**Confidence:** HIGH - Claude Code CLI is Anthropic's official tool with 76.2k+ GitHub stars. Documentation current as of 2026.

### OpenClaw Skill Framework

| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
| Python | 3.9+ | Core language | Required by libtmux and OpenClaw skills. Type hints available. |
| pathlib | stdlib | Path handling | Standard library, used in reference implementations. |
| json | stdlib | State persistence | Standard library, lightweight state management. |
| argparse | stdlib | CLI interface | Standard library, matches dev-workflow pattern. |

**OpenClaw Skill Structure (from dev-workflow reference):**
```
skill-name/
  SKILL.md           # YAML frontmatter + documentation
  orchestrator.py    # Main orchestration logic
  state_manager.py   # State persistence layer
  prompts/           # Prompt templates (optional)
```

**Confidence:** HIGH - Direct reference implementation available in `dev-workflow` skill.

### State Management

| Technology | Version | Purpose | Why |
|------------|---------|---------|-----|
| JSON files | N/A | Workflow state persistence | Simple, human-readable, matches OpenClaw pattern. Store in `.planning/gsd-openclaw/state.json`. |
| datetime | stdlib | Timestamps | ISO format timestamps for tracking phase transitions. |

**State schema pattern (from dev-workflow):**
```json
{
  "schema": "gsd-openclaw-state-v1",
  "current_phase": 1,
  "started_at": "2026-03-10T18:00:00+08:00",
  "updated_at": "2026-03-10T19:30:00+08:00",
  "phases": {
    "1": {"name": "Initialization", "status": "in_progress", "data": {}}
  },
  "context": {
    "trigger_message": "...",
    "working_directory": "..."
  }
}
```

**Confidence:** HIGH - Proven pattern from dev-workflow reference.

## What NOT to Use

| Category | Rejected | Why Not |
|----------|----------|---------|
| tmux CLI directly | Raw subprocess calls to tmux | Fragile string parsing. Use libtmux for type-safe ORM API. |
| pexpect | Python expect library | Unnecessary abstraction. libtmux handles I/O cleanly. |
| screen | Alternative to tmux | Less Python support, smaller ecosystem. tmux + libtmux is the standard. |
| SQLite | State persistence | Overkill for simple state files. JSON is sufficient and matches OpenClaw patterns. |
| asyncio | Async I/O | tmux session management is inherently synchronous. Adds complexity without benefit. |
| Third-party state managers | Redis, etc. | External dependencies. JSON files are portable and debuggable. |
| npm installation for Claude CLI | `npm install -g @anthropic-ai/claude-code` | Deprecated per docs. Use `curl -fsSL https://claude.ai/install.sh \| bash` for installation. |

## Installation

```bash
# Core dependencies
pip install libtmux==0.46.2

# Claude CLI (official installation)
curl -fsSL https://claude.ai/install.sh | bash

# Verify installations
python3 -c "import libtmux; print(libtmux.__version__)"
claude --version
tmux -V
```

## Architecture Integration

```
                    ┌─────────────────┐
                    │  Messaging App  │
                    │ (WeChat/Feishu) │
                    └────────┬────────┘
                             │
                             ▼
                    ┌─────────────────┐
                    │   OpenClaw      │
                    │   Agent         │
                    └────────┬────────┘
                             │
                             ▼
┌────────────────────────────────────────────────────────┐
│                  gsd-openclaw Skill                     │
│  ┌─────────────┐  ┌─────────────┐  ┌───────────────┐  │
│  │ SKILL.md    │  │orchestrator │  │state_manager  │  │
│  │ (triggers)  │  │    .py      │  │    .py        │  │
│  └─────────────┘  └──────┬──────┘  └───────────────┘  │
│                          │                             │
│                          ▼                             │
│                  ┌─────────────┐                       │
│                  │   libtmux   │                       │
│                  │  (v0.46.2)  │                       │
│                  └──────┬──────┘                       │
└─────────────────────────┼──────────────────────────────┘
                          │
                          ▼
                  ┌─────────────┐
                  │    tmux     │
                  │  session    │
                  └──────┬──────┘
                         │
                         ▼
                  ┌─────────────┐
                  │ Claude CLI  │
                  │   (GSD)     │
                  └─────────────┘
```

## Version Verification

| Component | Source | Date Verified |
|-----------|--------|---------------|
| libtmux | PyPI (https://pypi.org/project/libtmux/) | 2026-03-10 |
| Claude Code | Anthropic Docs (https://docs.anthropic.com/en/docs/claude-code/overview) | 2026-03-10 |
| OpenClaw patterns | dev-workflow skill reference | 2026-03-10 |

## Sources

- libtmux PyPI: https://pypi.org/project/libtmux/ (v0.46.2, May 26, 2025)
- libtmux GitHub: https://github.com/tmux-python/libtmux
- 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
- Claude Code GitHub: https://github.com/anthropics/claude-code
- OpenClaw dev-workflow skill: `/home/starmen1265/.openclaw/skills/dev-workflow/`