oh-my-codex-cli 0.1.0

package/.agent/skills/project-session-manager/SKILL.md

@@ -0,0 +1,428 @@
+---
+name: project-session-manager
+description: Manage isolated dev environments with git worktrees and tmux sessions
+aliases: [psm]
+---
+
+# Project Session Manager (PSM) Skill
+
+
+## Native Subagent Protocol (Codex)
+
+Codex supports native subagents. Delegate with `spawn_agent`, coordinate with `send_input`, collect via `wait`, and clean up with `close_agent`.
+
+Execution preference:
+1. Use native subagents first for independent workstreams (parallel when possible).
+2. Merge results in main thread and run final verification.
+3. Fallback only when delegation is blocked: use the `[ANALYST]`/`[ARCHITECT]`/`[EXECUTOR]`/`[REVIEWER]` structure in a single response.
+
+Minimal orchestration pattern:
+```text
+spawn_agent -> send_input (optional) -> wait -> close_agent
+```
+
+> Codex invocation: use `$project-session-manager ...` or `project-session-manager: ...`
+
+
+Automate isolated development environments using git worktrees and tmux sessions with Codex. Enables parallel work across multiple tasks, projects, and repositories.
+
+## Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `review <ref>` | PR review session | `$psm review omc#123` |
+| `fix <ref>` | Issue fix session | `$psm fix omc#42` |
+| `feature <proj> <name>` | Feature development | `$psm feature omc add-webhooks` |
+| `list [project]` | List active sessions | `$psm list` |
+| `attach <session>` | Attach to session | `$psm attach omc:pr-123` |
+| `kill <session>` | Kill session | `$psm kill omc:pr-123` |
+| `cleanup` | Clean merged/closed | `$psm cleanup` |
+| `status` | Current session info | `$psm status` |
+
+## Project References
+
+Supported formats:
+- **Alias**: `omc#123` (requires `~/.psm/projects.json`)
+- **Full**: `owner/repo#123`
+- **URL**: `https://github.com/owner/repo/pull/123`
+- **Current**: `#123` (uses current directory's repo)
+
+## Configuration
+
+### Project Aliases (`~/.psm/projects.json`)
+
+```json
+{
+  "aliases": {
+    "omc": {
+      "repo": "Yeachan-Heo/oh-my-codex",
+      "local": "~/Workspace/oh-my-codex",
+      "default_base": "main"
+    }
+  },
+  "defaults": {
+    "worktree_root": "~/.psm/worktrees",
+    "cleanup_after_days": 14
+  }
+}
+```
+
+## Directory Structure
+
+```
+~/.psm/
+├── projects.json       # Project aliases
+├── sessions.json       # Active session registry
+└── worktrees/          # Worktree storage
+    └── <project>/
+        └── <type>-<id>/
+```
+
+## Session Naming
+
+| Type | Tmux Session | Worktree Dir |
+|------|--------------|--------------|
+| PR Review | `psm:omc:pr-123` | `~/.psm/worktrees/omc/pr-123` |
+| Issue Fix | `psm:omc:issue-42` | `~/.psm/worktrees/omc/issue-42` |
+| Feature | `psm:omc:feat-auth` | `~/.psm/worktrees/omc/feat-auth` |
+
+---
+
+## Implementation Protocol
+
+When the user invokes a PSM command, follow this protocol:
+
+### Parse Arguments
+
+Parse `{{ARGUMENTS}}` to determine:
+1. **Subcommand**: review, fix, feature, list, attach, kill, cleanup, status
+2. **Reference**: project#number, URL, or session ID
+3. **Options**: --branch, --base, --no-codex, --no-tmux, etc.
+
+### Subcommand: `review <ref>`
+
+**Purpose**: Create PR review session
+
+**Steps**:
+
+1. **Resolve reference**:
+   ```bash
+   # Read project aliases
+   cat ~/.psm/projects.json 2>/dev/null || echo '{"aliases":{}}'
+
+   # Parse ref format: alias#num, owner/repo#num, or URL
+   # Extract: project_alias, repo (owner/repo), pr_number, local_path
+   ```
+
+2. **Fetch PR info**:
+   ```bash
+   gh pr view <pr_number> --repo <repo> --json number,title,author,headRefName,baseRefName,body,files,url
+   ```
+
+3. **Ensure local repo exists**:
+   ```bash
+   # If local path doesn't exist, clone
+   if [[ ! -d "$local_path" ]]; then
+     git clone "https://github.com/$repo.git" "$local_path"
+   fi
+   ```
+
+4. **Create worktree**:
+   ```bash
+   worktree_path="$HOME/.psm/worktrees/$project_alias/pr-$pr_number"
+
+   # Fetch PR branch
+   cd "$local_path"
+   git fetch origin "pull/$pr_number/head:pr-$pr_number-review"
+
+   # Create worktree
+   git worktree add "$worktree_path" "pr-$pr_number-review"
+   ```
+
+5. **Create session metadata**:
+   ```bash
+   cat > "$worktree_path/.psm-session.json" << EOF
+   {
+     "id": "$project_alias:pr-$pr_number",
+     "type": "review",
+     "project": "$project_alias",
+     "ref": "pr-$pr_number",
+     "branch": "<head_branch>",
+     "base": "<base_branch>",
+     "created_at": "$(date -Iseconds)",
+     "tmux_session": "psm:$project_alias:pr-$pr_number",
+     "worktree_path": "$worktree_path",
+     "source_repo": "$local_path",
+     "github": {
+       "pr_number": $pr_number,
+       "pr_title": "<title>",
+       "pr_author": "<author>",
+       "pr_url": "<url>"
+     },
+     "state": "active"
+   }
+   EOF
+   ```
+
+6. **Update sessions registry**:
+   ```bash
+   # Add to ~/.psm/sessions.json
+   ```
+
+7. **Create tmux session**:
+   ```bash
+   tmux new-session -d -s "psm:$project_alias:pr-$pr_number" -c "$worktree_path"
+   ```
+
+8. **Launch Codex** (unless --no-codex):
+   ```bash
+   tmux send-keys -t "psm:$project_alias:pr-$pr_number" "codex" Enter
+   ```
+
+9. **Output session info**:
+   ```
+   Session ready!
+
+     ID: omc:pr-123
+     Worktree: ~/.psm/worktrees/omc/pr-123
+     Tmux: psm:omc:pr-123
+
+   To attach: tmux attach -t psm:omc:pr-123
+   ```
+
+### Subcommand: `fix <ref>`
+
+**Purpose**: Create issue fix session
+
+**Steps**:
+
+1. **Resolve reference** (same as review)
+
+2. **Fetch issue info**:
+   ```bash
+   gh issue view <issue_number> --repo <repo> --json number,title,body,labels,url
+   ```
+
+3. **Create feature branch**:
+   ```bash
+   cd "$local_path"
+   git fetch origin main
+   branch_name="fix/$issue_number-$(echo "$title" | tr ' ' '-' | tr '[:upper:]' '[:lower:]' | head -c 30)"
+   git checkout -b "$branch_name" origin/main
+   ```
+
+4. **Create worktree**:
+   ```bash
+   worktree_path="$HOME/.psm/worktrees/$project_alias/issue-$issue_number"
+   git worktree add "$worktree_path" "$branch_name"
+   ```
+
+5. **Create session metadata** (similar to review, type="fix")
+
+6. **Update registry, create tmux, launch codex** (same as review)
+
+### Subcommand: `feature <project> <name>`
+
+**Purpose**: Start feature development
+
+**Steps**:
+
+1. **Resolve project** (from alias or path)
+
+2. **Create feature branch**:
+   ```bash
+   cd "$local_path"
+   git fetch origin main
+   branch_name="feature/$feature_name"
+   git checkout -b "$branch_name" origin/main
+   ```
+
+3. **Create worktree**:
+   ```bash
+   worktree_path="$HOME/.psm/worktrees/$project_alias/feat-$feature_name"
+   git worktree add "$worktree_path" "$branch_name"
+   ```
+
+4. **Create session, tmux, launch codex** (same pattern)
+
+### Subcommand: `list [project]`
+
+**Purpose**: List active sessions
+
+**Steps**:
+
+1. **Read sessions registry**:
+   ```bash
+   cat ~/.psm/sessions.json 2>/dev/null || echo '{"sessions":{}}'
+   ```
+
+2. **Check tmux sessions**:
+   ```bash
+   tmux list-sessions -F "#{session_name}" 2>/dev/null | grep "^psm:"
+   ```
+
+3. **Check worktrees**:
+   ```bash
+   ls -la ~/.psm/worktrees/*/ 2>/dev/null
+   ```
+
+4. **Format output**:
+   ```
+   Active PSM Sessions:
+
+   ID                 | Type    | Status   | Worktree
+   -------------------|---------|----------|---------------------------
+   omc:pr-123        | review  | active   | ~/.psm/worktrees/omc/pr-123
+   omc:issue-42      | fix     | detached | ~/.psm/worktrees/omc/issue-42
+   ```
+
+### Subcommand: `attach <session>`
+
+**Purpose**: Attach to existing session
+
+**Steps**:
+
+1. **Parse session ID**: `project:type-number`
+
+2. **Verify session exists**:
+   ```bash
+   tmux has-session -t "psm:$session_id" 2>/dev/null
+   ```
+
+3. **Attach**:
+   ```bash
+   tmux attach -t "psm:$session_id"
+   ```
+
+### Subcommand: `kill <session>`
+
+**Purpose**: Kill session and cleanup
+
+**Steps**:
+
+1. **Kill tmux session**:
+   ```bash
+   tmux kill-session -t "psm:$session_id" 2>/dev/null
+   ```
+
+2. **Remove worktree**:
+   ```bash
+   worktree_path=$(jq -r ".sessions[\"$session_id\"].worktree" ~/.psm/sessions.json)
+   source_repo=$(jq -r ".sessions[\"$session_id\"].source_repo" ~/.psm/sessions.json)
+
+   cd "$source_repo"
+   git worktree remove "$worktree_path" --force
+   ```
+
+3. **Update registry**:
+   ```bash
+   # Remove from sessions.json
+   ```
+
+### Subcommand: `cleanup`
+
+**Purpose**: Clean up merged PRs and closed issues
+
+**Steps**:
+
+1. **Read all sessions**
+
+2. **For each PR session, check if merged**:
+   ```bash
+   gh pr view <pr_number> --repo <repo> --json merged,state
+   ```
+
+3. **For each issue session, check if closed**:
+   ```bash
+   gh issue view <issue_number> --repo <repo> --json closed,state
+   ```
+
+4. **Clean up merged/closed sessions**:
+   - Kill tmux session
+   - Remove worktree
+   - Update registry
+
+5. **Report**:
+   ```
+   Cleanup complete:
+     Removed: omc:pr-123 (merged)
+     Removed: omc:issue-42 (closed)
+     Kept: omc:feat-auth (active)
+   ```
+
+### Subcommand: `status`
+
+**Purpose**: Show current session info
+
+**Steps**:
+
+1. **Detect current session** from tmux or cwd:
+   ```bash
+   tmux display-message -p "#{session_name}" 2>/dev/null
+   # or check if cwd is inside a worktree
+   ```
+
+2. **Read session metadata**:
+   ```bash
+   cat .psm-session.json 2>/dev/null
+   ```
+
+3. **Show status**:
+   ```
+   Current Session: omc:pr-123
+   Type: review
+   PR: #123 - Add webhook support
+   Branch: feature/webhooks
+   Created: 2 hours ago
+   ```
+
+---
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Worktree exists | Offer: attach, recreate, or abort |
+| PR not found | Verify URL/number, check permissions |
+| No tmux | Warn and skip session creation |
+| No gh CLI | Error with install instructions |
+
+## Requirements
+
+- `git` with worktree support (v2.5+)
+- `gh` CLI (authenticated)
+- `tmux`
+- `jq` for JSON parsing
+
+## Initialization
+
+On first run, create default config:
+
+```bash
+mkdir -p ~/.psm/worktrees ~/.psm/logs
+
+# Create default projects.json if not exists
+if [[ ! -f ~/.psm/projects.json ]]; then
+  cat > ~/.psm/projects.json << 'EOF'
+{
+  "aliases": {
+    "omc": {
+      "repo": "Yeachan-Heo/oh-my-codex",
+      "local": "~/Workspace/oh-my-codex",
+      "default_base": "main"
+    }
+  },
+  "defaults": {
+    "worktree_root": "~/.psm/worktrees",
+    "cleanup_after_days": 14,
+    "auto_cleanup_merged": true
+  }
+}
+EOF
+fi
+
+# Create sessions.json if not exists
+if [[ ! -f ~/.psm/sessions.json ]]; then
+  echo '{"version":1,"sessions":{},"stats":{"total_created":0,"total_cleaned":0}}' > ~/.psm/sessions.json
+fi
+```

package/.agent/skills/project-session-manager/lib/config.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+# PSM Configuration Management
+
+PSM_ROOT="${HOME}/.psm"
+PSM_WORKTREES="${PSM_ROOT}/worktrees"
+PSM_PROJECTS="${PSM_ROOT}/projects.json"
+PSM_SESSIONS="${PSM_ROOT}/sessions.json"
+PSM_LOGS="${PSM_ROOT}/logs"
+
+# Initialize PSM directories and config files
+psm_init() {
+    mkdir -p "$PSM_WORKTREES" "$PSM_LOGS"
+
+    # Create default projects.json if not exists
+    if [[ ! -f "$PSM_PROJECTS" ]]; then
+        cat > "$PSM_PROJECTS" << 'EOF'
+{
+  "aliases": {
+    "omc": {
+      "repo": "Yeachan-Heo/oh-my-codex",
+      "local": "~/Workspace/oh-my-codex",
+      "default_base": "main"
+    }
+  },
+  "defaults": {
+    "worktree_root": "~/.psm/worktrees",
+    "cleanup_after_days": 14,
+    "auto_cleanup_merged": true
+  }
+}
+EOF
+        echo "Created default projects.json"
+    fi
+
+    # Create sessions.json if not exists
+    if [[ ! -f "$PSM_SESSIONS" ]]; then
+        echo '{"version":1,"sessions":{},"stats":{"total_created":0,"total_cleaned":0}}' > "$PSM_SESSIONS"
+        echo "Created sessions.json"
+    fi
+}
+
+# Get project config by alias
+# Usage: psm_get_project "omc"
+# Returns: repo|local|default_base
+psm_get_project() {
+    local alias="$1"
+    if [[ ! -f "$PSM_PROJECTS" ]]; then
+        return 1
+    fi
+
+    local repo=$(jq -r ".aliases[\"$alias\"].repo // empty" "$PSM_PROJECTS")
+    local local_path=$(jq -r ".aliases[\"$alias\"].local // empty" "$PSM_PROJECTS")
+    local default_base=$(jq -r ".aliases[\"$alias\"].default_base // \"main\"" "$PSM_PROJECTS")
+
+    if [[ -z "$repo" ]]; then
+        return 1
+    fi
+
+    # Expand ~ to $HOME
+    local_path="${local_path/#\~/$HOME}"
+
+    echo "${repo}|${local_path}|${default_base}"
+}
+
+# Add or update project alias
+psm_set_project() {
+    local alias="$1"
+    local repo="$2"
+    local local_path="$3"
+    local default_base="${4:-main}"
+
+    local tmp=$(mktemp)
+    jq ".aliases[\"$alias\"] = {\"repo\": \"$repo\", \"local\": \"$local_path\", \"default_base\": \"$default_base\"}" \
+        "$PSM_PROJECTS" > "$tmp" && mv "$tmp" "$PSM_PROJECTS"
+}
+
+# Get default worktree root
+psm_get_worktree_root() {
+    local root=$(jq -r '.defaults.worktree_root // "~/.psm/worktrees"' "$PSM_PROJECTS")
+    echo "${root/#\~/$HOME}"
+}
+
+# Get cleanup days setting
+psm_get_cleanup_days() {
+    jq -r '.defaults.cleanup_after_days // 14' "$PSM_PROJECTS"
+}

package/.agent/skills/project-session-manager/lib/parse.sh

@@ -0,0 +1,121 @@
+#!/bin/bash
+# PSM Reference Parser
+
+# Parse a reference string into components
+# Supports:
+#   omc#123           -> alias=omc, number=123
+#   owner/repo#123    -> repo=owner/repo, number=123
+#   https://...       -> parsed from URL
+#   #123              -> number=123 (use current repo)
+#
+# Usage: psm_parse_ref "omc#123"
+# Returns: type|alias|repo|number|local_path|base
+psm_parse_ref() {
+    local ref="$1"
+    local type=""
+    local alias=""
+    local repo=""
+    local number=""
+    local local_path=""
+    local base="main"
+
+    # GitHub PR URL
+    if [[ "$ref" =~ ^https://github\.com/([^/]+)/([^/]+)/pull/([0-9]+) ]]; then
+        repo="${BASH_REMATCH[1]}/${BASH_REMATCH[2]}"
+        number="${BASH_REMATCH[3]}"
+        type="pr"
+        # Try to find alias for this repo
+        alias=$(psm_find_alias_for_repo "$repo")
+        if [[ -n "$alias" ]]; then
+            IFS='|' read -r _ local_path base <<< "$(psm_get_project "$alias")"
+        fi
+        echo "pr|${alias:-}|$repo|$number|${local_path:-}|$base"
+        return 0
+    fi
+
+    # GitHub Issue URL
+    if [[ "$ref" =~ ^https://github\.com/([^/]+)/([^/]+)/issues/([0-9]+) ]]; then
+        repo="${BASH_REMATCH[1]}/${BASH_REMATCH[2]}"
+        number="${BASH_REMATCH[3]}"
+        type="issue"
+        alias=$(psm_find_alias_for_repo "$repo")
+        if [[ -n "$alias" ]]; then
+            IFS='|' read -r _ local_path base <<< "$(psm_get_project "$alias")"
+        fi
+        echo "issue|${alias:-}|$repo|$number|${local_path:-}|$base"
+        return 0
+    fi
+
+    # alias#number format (e.g., omc#123)
+    if [[ "$ref" =~ ^([a-zA-Z][a-zA-Z0-9_-]*)#([0-9]+)$ ]]; then
+        alias="${BASH_REMATCH[1]}"
+        number="${BASH_REMATCH[2]}"
+
+        local project_info
+        project_info=$(psm_get_project "$alias")
+        if [[ $? -eq 0 ]]; then
+            IFS='|' read -r repo local_path base <<< "$project_info"
+            # Determine type from context (default to issue, caller specifies)
+            echo "ref|$alias|$repo|$number|$local_path|$base"
+            return 0
+        else
+            echo "error|Unknown project alias: $alias|||"
+            return 1
+        fi
+    fi
+
+    # owner/repo#number format
+    if [[ "$ref" =~ ^([a-zA-Z0-9_-]+)/([a-zA-Z0-9_.-]+)#([0-9]+)$ ]]; then
+        repo="${BASH_REMATCH[1]}/${BASH_REMATCH[2]}"
+        number="${BASH_REMATCH[3]}"
+        alias=$(psm_find_alias_for_repo "$repo")
+        if [[ -n "$alias" ]]; then
+            IFS='|' read -r _ local_path base <<< "$(psm_get_project "$alias")"
+        fi
+        echo "ref|${alias:-}|$repo|$number|${local_path:-}|$base"
+        return 0
+    fi
+
+    # Just #number (use current repo)
+    if [[ "$ref" =~ ^#([0-9]+)$ ]]; then
+        number="${BASH_REMATCH[1]}"
+        # Detect repo from current directory
+        if git rev-parse --git-dir > /dev/null 2>&1; then
+            local remote_url=$(git remote get-url origin 2>/dev/null)
+            if [[ "$remote_url" =~ github\.com[:/]([^/]+)/([^/.]+) ]]; then
+                repo="${BASH_REMATCH[1]}/${BASH_REMATCH[2]}"
+                local_path=$(git rev-parse --show-toplevel)
+                alias=$(psm_find_alias_for_repo "$repo")
+            fi
+        fi
+        echo "ref|${alias:-}|${repo:-}|$number|${local_path:-}|$base"
+        return 0
+    fi
+
+    echo "error|Cannot parse reference: $ref|||"
+    return 1
+}
+
+# Find project alias for a given repo
+psm_find_alias_for_repo() {
+    local target_repo="$1"
+    if [[ ! -f "$PSM_PROJECTS" ]]; then
+        return 1
+    fi
+
+    jq -r ".aliases | to_entries[] | select(.value.repo == \"$target_repo\") | .key" "$PSM_PROJECTS" | head -1
+}
+
+# Sanitize a string for use in filenames/session names
+psm_sanitize() {
+    local input="$1"
+    # Remove path traversal, convert to lowercase, replace spaces with dashes
+    echo "$input" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9-]/-/g' | sed 's/--*/-/g' | head -c 30
+}
+
+# Generate a slug from title
+psm_slugify() {
+    local title="$1"
+    local max_len="${2:-30}"
+    echo "$title" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//' | sed 's/-$//' | head -c "$max_len"
+}