project-session-manager

Files (19)

• SKILL.md
• config.sh · lib/
• parse.sh · lib/
• azure-devops.sh · lib/providers/
• bitbucket.sh · lib/providers/
• gitea.sh · lib/providers/
• github.sh · lib/providers/
• gitlab.sh · lib/providers/
• interface.sh · lib/providers/
• jira.sh · lib/providers/
• session.sh · lib/
• tmux.sh · lib/
• worktree.sh · lib/
• psm.sh
• skill.manifest.json
• feature.md · templates/
• issue-fix.md · templates/
• pr-review.md · templates/
• projects.json · templates/

SKILL.md (first lines)

# Project Session Manager (PSM) Skill

> **Quick Start:** For simple worktree creation without tmux sessions, use `superskills teleport`:
> ```bash
> superskills teleport #123          # Create worktree for issue/PR
> superskills teleport my-feature    # Create worktree for feature
> superskills teleport list          # List worktrees
> ```
> See [Teleport Command](#teleport-command) below for details.

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 | `/superskills:project-session-manager review superskills#123` |
| `fix <ref>` | Issue fix session | `/superskills:project-session-manager fix superskills#42` |
| `feature <proj> <name>` | Feature development | `/superskills:project-session-manager feature superskills add-webhooks` |
| `list [project]` | List active sessions | `/superskills:project-session-manager list` |
| `attach <session>` | Attach to session | `/superskills:project-session-manager attach superskills:pr-123` |
| `kill <session>` | Kill session | `/superskills:project-session-manager kill superskills:pr-123` |
| `cleanup` | Clean merged/closed | `/superskills:project-session-manager cleanup` |
| `status` | Current session info | `/superskills:project-session-manager status` |

## Project References

Supported formats:
- **Alias**: `superskills#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": {
    "superskills": {
      "repo": "shaun0927/codex-superskills",
      "local": "~/Workspace/codex-superskills",
      "default_base": "main"
    }
  },
  "defaults": {
    "worktree_root": "~/.psm/worktrees",
    "cleanup_after_days": 14
  }
}
```

## Providers

PSM supports multiple issue tracking providers:

| Provider | CLI Required | Reference Formats | Commands |
|----------|--------------|-------------------|----------|
| GitHub (default) | `gh` | `owner/repo#123`, `alias#123`, GitHub URLs | review, fix, feature |
| Jira | `jira` | `PROJ-123` (if PROJ configured), `alias#123` | fix, feature |

### Jira Configuration

To use Jira, add an alias with `jira_project` and `provider: "jira"`:

```json
{
  "aliases": {
    "mywork": {
      "jira_project": "MYPROJ",
      "repo": "mycompany/my-project",
      "local": "~/Workspace/my-project",
      "default_base": "main",
      "provider": "jira"
    }
  }
}
```

**Important:** The `repo` field is still required for cloning the git repository. Jira tracks issues, but you work in a git repo.

For non-GitHub repos, use `clone_url` instead:
```json
{
  "aliases": {
    "private": {
      "jira_project": "PRIV",
      "clone_url": "git@gitlab.internal:team/repo.git",
      "local": "~/Workspace/repo",
      "provider": "jira"
    }
  }
}
```

### Jira Reference Detection

PSM only recognizes `PROJ-123` format as Jira when `PROJ` is explicitly configured as a `jira_project` in your aliases. This prevents false positives from branch names like `FIX-123`.

### Jira Examples

```bash
# Fix a Jira issue (MYPROJ must be configured)
psm fix MYPROJ-123

# Fix using alias (recommended)
psm fix mywork#123

# Feature development (works same as GitHub)
psm feature mywork add-webhooks

# Note: 'psm review' is not supported for Jira (no PR concept)
# Use 'psm fix' for Jira issues
```

### Jira CLI Setup

Install the Jira CLI:

From shaun0927/codex-superskills, MIT.

More from shaun0927/codex-superskills