Guide · Agent skill

How to use the Project Session Manager agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Project Session Manager (PSM) is an agent skill for Claude Code that gives each issue, pull request or feature its own git worktree, which is a second checkout of the same repository in a separate folder. It can also start a named tmux terminal session for that work and keep a registry of sessions so you can list, attach to or clean them up later. This guide explains what the skill does, how to install it, how to ask for it in plain language, and what it needs to run safely.

Project Session ManagerYeachan-Heo/oh-my-claudecode · MIT Download the skill

Quick start

1Download and unzip. Download the skill ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder.
2Install the required tools. Make sure bash, git and jq are available, plus gh for GitHub work and tmux if you want sessions.
3Create ~/.psm/projects.json. Add an alias for your repository with its repo name and local path so PSM can find your clone.
4Ask for a task in plain language. Request a PR review, issue fix or feature, for example Review PR 123 in omc in a separate worktree.
5Work in the new worktree. Claude Code runs in the isolated worktree at ~/.psm/worktrees, leaving your main branch unchanged.
6List and attach to sessions. Use psm list to see active sessions and psm attach omc:pr-123 or tmux attach -t psm_omc_pr-123 to return to one.
7Clean up when finished. Run psm cleanup to remove sessions for merged or closed work.

What is an agent skill, and what does this one do?

An agent skill is a folder containing a SKILL.md instruction file and supporting files that Claude Code can load when a request matches the skill's description. This skill is named project-session-manager and is also available under the alias psm.

When you ask Claude Code to review a pull request, fix an issue or start a feature, the skill creates a separate git worktree for that task. Your main branch and working folder stay untouched, so you can switch between tasks without stashing or committing half-finished work.

Review: create a worktree for a PR review session
Fix: create a worktree for an issue fix session
Feature: create a worktree for feature development
List, attach, kill and clean up sessions, and show status of the current session

How do you install the project-session-manager skill?

Download the ZIP file for this skill from this page and unzip it. You can install it in one of two places, depending on whether you want it available everywhere or only in one project.

For all your projects, place the unzipped skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. Claude Code will pick it up from either location.

You can also upload the skill in the Claude apps. Open Settings, go to Capabilities, then Skills, and upload it there.

Personal install: ~/.claude/skills/
Project install: .claude/skills/ inside your repository
Claude apps: Settings → Capabilities → Skills

Install the tools PSM depends on

The skill is a set of shell scripts, so it needs a few command-line tools. Which ones you need depends on your work. GitHub work needs the gh CLI. Git worktrees need git itself. The scripts also use jq.

Required: bash, git, jq
Required for GitHub work: gh (GitHub CLI)
Optional: tmux, for named terminal sessions
Jira aliases: the jira CLI
Azure DevOps: the az CLI
Bitbucket: curl. Bitbucket, GitLab and Gitea can also use tokens you configure yourself through BITBUCKET environment variables and their APIs

Configure project aliases

PSM can use short aliases such as omc#123 instead of full repository names. Aliases are defined in ~/.psm/projects.json. Each alias names the repository and, optionally, the local path where you already have a clone. The defaults section sets the worktree root and how many days to keep finished sessions before cleanup.

If the local path does not exist, the review command clones the repository. For Jira, the repo field is still required because Jira tracks issues while the code lives in git.

repo: owner/repo name, used for cloning and PR lookup
local: path to your existing clone
default_base: branch to base work on, such as main
worktree_root defaults to ~/.psm/worktrees in the example config
cleanup_after_days: 14 in the example config

{
  "aliases": {
    "omc": {
      "repo": "Yeachan-Heo/oh-my-claudecode",
      "local": "~/Workspace/oh-my-claudecode",
      "default_base": "main"
    }
  },
  "defaults": {
    "worktree_root": "~/.psm/worktrees",
    "cleanup_after_days": 14
  }
}

Trigger the skill with natural requests

You do not need to memorise the command syntax. Describe the task and mention the issue, pull request or feature. The skill also accepts the explicit commands, and the slash form is /oh-my-claudecode:project-session-manager (or /oh-my-claudecode:psm).

Project references can be written as an alias (omc#123), a full name (owner/repo#123), a GitHub URL, or #123 for the repository in your current directory.

"Review PR 123 in omc in a separate worktree"
"Set up a worktree to fix issue 42 in omc"
"Start a feature branch called add-webhooks in omc"
"Show my active PSM sessions"
"Clean up sessions for merged or closed PRs"

/psm review omc#123
/psm fix omc#42
/psm feature omc add-webhooks
/psm list
/psm attach omc:pr-123
/psm kill omc:pr-123
/psm cleanup
/psm status

Use the quick worktree command for isolation only

If you only want an isolated worktree without tmux or session orchestration, the skill documents a worktree-first entry point called omc teleport. Use it when you just need a clean folder for one issue, PR or feature.

omc teleport #123
omc teleport my-feature
omc teleport list

Know where files and sessions live

PSM keeps its state under ~/.psm/. The session registry is sessions.json, aliases are in projects.json, and each worktree sits in a folder named by project and task type. Session IDs use a colon form such as omc:pr-123 with psm attach and psm kill, but the actual tmux session uses underscores, such as psm_omc_pr-123. Attach to the tmux name directly with tmux attach.

~/.psm/projects.json: project aliases
~/.psm/sessions.json: active session registry
~/.psm/worktrees/<project>/<type>-<id>/: worktree storage

tmux attach -t psm_omc_pr-123

Safety: what the skill runs and touches

This skill runs shell scripts on your machine and uses the network. It can clone repositories, fetch pull request data through the gh CLI, and call provider APIs. It also creates files and folders under ~/.psm/ and writes a .psm-session.json metadata file into each worktree. Review the scripts in the skill folder before you install it, especially if you are working on a shared or sensitive machine.

For review sessions, PSM launches Claude Code with the --dangerously-skip-permissions flag so that the trust prompt and tool approval prompts do not stall the session. Understand what this flag means before you use the review flow.

Runs scripts: yes
Uses network: yes
Writes to ~/.psm and clones repositories when a local path is missing
Creates a .psm-session.json file in each worktree

Tips for getting the most from it

Use separate worktrees for every task you would otherwise switch between in one checkout. Keep your local aliases up to date so the skill finds your existing clones. Run cleanup once PRs are merged or closed to keep the registry tidy. Jira users should note that psm review is not supported because Jira has no pull request concept.

For Jira, configure the jira_project key so PROJ-123 references are recognised
Use psm status to confirm which session you are in before editing
Do not use this skill for quick single-file edits where one checkout is enough

What people use it for

Reviewing a pull request in its own folder while your feature branch stays open in your main checkout
Fixing several GitHub issues in parallel, each in its own worktree and tmux session
Working on a Jira issue with an alias so the code lives in a git repo that Jira tracks separately
Starting a named feature branch with its own worktree and a context template for the work

Frequently asked questions

Is the project-session-manager skill free?

The skill is released under the MIT licence, as stated on this page. Check the licence file in the repository for the full terms before you use or redistribute it.

What do I need installed to use it?

You need bash, git and jq. Add gh (GitHub CLI) for GitHub work, tmux if you want named sessions, and the jira, az or curl tools for Jira, Azure DevOps and Bitbucket respectively.

Where do I put the skill folder?

Place the unzipped folder in ~/.claude/skills/ to use it across projects, or in a project's .claude/skills/ folder to limit it to that project. You can also upload it in the Claude apps under Settings → Capabilities → Skills.

What is the difference between a worktree and a branch?

A branch is a line of commits in a repository. A git worktree is an extra checkout of the same repository in a separate folder, so you can have several branches checked out at once without switching in your main folder.

Does it work with GitLab, Jira or Azure DevOps?

The source lists provider scripts for GitHub, Jira, Azure DevOps, Bitbucket, GitLab and Gitea. GitHub is the default, and Jira aliases work for fix and feature commands. Review is not supported for Jira.

Why did my tmux session name not match the ID I typed?

tmux does not allow colons or dots in session names, so PSM uses underscores in the tmux name. For example, omc:pr-123 becomes psm_omc_pr-123. Use psm attach with the public ID or tmux attach -t with the tmux name.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits developers who work on several issues or pull requests in one repository and want a clean folder and optional terminal session for each. Skip it for simple single-file edits, and avoid it if you do not want shell scripts run on your machine or files written to ~/.psm.

Download the skill