claude-ls

CLI tool for managing Claude Code projects.

⚠️ Disclaimer: This is not an official Anthropic tool. The logic has been implemented by reverse-engineering the documentation and the ~/.claude directory structure. Use at your own risk.

You're working in the terminal, you create a new folder, start a Claude Code session, build out your project... and then realise the folder name is wrong. Maybe it's a typo, maybe the scope changed, maybe you just want to reorganise.

Normally you'd just mv the folder. But Claude Code stores session history, permissions, and settings in ~/.claude/ keyed by the project path. Rename the folder and Claude loses track: your conversation history, your approved tools, your MCP configs all become orphaned.

claude-ls was born to fix this. It moves your project directory and updates all the internal references, so you keep your full context and chat history intact.

But it grew from there. claude-ls is the project management CLI that Claude Code doesn't have yet: list your projects, inspect their settings, search across them, and clean up what's left behind.

git clone https://github.com/gverni/claude-ls.git
cd claude-ls
npm install
npm link

This makes the claude-ls command available globally on your system.

Requires Node.js >= 18.

List all projects tracked by Claude Code.

claude-ls list                        # List all projects (alphabetical)
claude-ls list --sort recent          # Sort by most recently used
claude-ls list --sort oldest          # Sort by least recently used
claude-ls list --orphaned             # Show only orphaned projects
claude-ls list --json                 # Output as JSON
claude-ls list --claude-dir <path>    # Override Claude data directory

Example output:

● ~/projects/my-app (git)
  ⎿  sessions: 5, last active: 2026-05-10 14:30
  ⎿  ● ~/projects/my-app/packages/frontend
     ⎿  sessions: 2, last active: 2026-05-09 11:00

● ~/projects/scripts
  ⎿  sessions: 3, last active: 2026-04-20 09:15

● ~/old/deleted-project (orphaned)
  ⎿  sessions: 2, last active: 2026-03-01 10:00

● ~/dev/some-project [jsonl]
  ⎿  sessions: 1, last active: 2026-02-10 08:00

Entry types:

• Project - a folder where you've run Claude Code. Can be a standalone directory or a git repo (marked with (git)).
• Subfolder - only applies to git repos. Shown indented under the parent project. Claude Code creates a separate session directory for each subdirectory you run it from, but permissions and MCP configs are stored on the git root.
• Worktree - shown indented under the parent repo, marked with (worktree). Git worktrees have their own directory on disk (possibly with a completely different path), but Claude Code tracks them under the main repository.
• Orphaned - marked with (orphaned). The directory no longer exists on disk but Claude still has data for it. Use claude-ls prune or claude project purge to clean up.

Source labels (shown when a project was not found in ~/.claude.json):

• [jsonl] - path was read from a session file's cwd field. This happens for git subfolders, worktrees, and any project whose ~/.claude.json entry is missing.
• [decoded] - path was guessed by decoding the directory name. This is a last resort and is lossy: dashes in the original path are indistinguishable from encoded slashes.

Show project properties: MCPs, allowed tools, sessions, CLAUDE.md, and plans.

claude-ls inspect                     # Interactive project picker
claude-ls inspect ~/projects/my-app   # Inspect a specific project
claude-ls inspect --json              # Output as JSON
claude-ls inspect --claude-dir <path>

Example output:

● /Users/gv/dev/my-app (git)

  CLAUDE.md
  ⎿  My App - Development Guide

  Plans (1)
  ⎿  Refactor auth layer  refactor-auth-layer.md

  MCPs
  ⎿  github  npx -y @modelcontextprotocol/server-github  (global)
  ⎿  local-tools  node ./mcp/server.js  (.mcp.json)

  Allowed tools
  ⎿  Bash, Read, Edit, Write  (global)
  ⎿  Bash(npm run *)  (settings.json)

  Sessions (3)
  ⎿  a1b2c3d4  created: 2026-05-01 09:00  last: 2026-05-10 14:30
  ⎿  e5f6g7h8  created: 2026-04-15 11:00  last: 2026-04-20 17:45
  ⎿  i9j0k1l2  created: 2026-03-01 10:00  last: 2026-03-01 10:00

Plans are matched by searching their content for the project path. This is a best-effort link - see implementation notes for details.

Move a project directory and update all Claude Code internal references.

claude-ls move ~/projects/old ~/projects/new
claude-ls move ~/old ~/new --dry-run          # Preview without changes
claude-ls move ~/old ~/new --yes              # Skip confirmation
claude-ls move ~/old ~/new --verbose          # Detailed output
claude-ls move ~/old ~/new --claude-dir <path>

Before moving, claude-ls move classifies the source path and adjusts its behaviour:

Update Claude Code references only (directory already moved manually).

Use this when you've already renamed or moved the folder yourself and just need Claude to catch up.

claude-ls remap ~/old/path ~/new/path
claude-ls remap ~/old ~/new --dry-run
claude-ls remap ~/old ~/new --yes
claude-ls remap ~/old ~/new --verbose
claude-ls remap ~/old ~/new --claude-dir <path>

Search for projects by path name.

claude-ls search payment                      # Find projects whose path contains "payment"
claude-ls search payment --sort recent        # Sort by most recently active
claude-ls search payment --sort oldest        # Sort by least recently active
claude-ls search payment --json               # Output as JSON
claude-ls search payment --claude-dir <path>

Search is case-insensitive and includes orphaned projects. Each result shows the session count and last active date.

Delete Claude Code data for an orphaned project. Try claude project purge first - use this only as a fallback if that command is not available on your system.

claude-ls prune                         # Interactive picker (scrollable, multi-select)
claude-ls prune ~/old/deleted-project   # Prune a specific orphaned project
claude-ls prune --all                   # Prune all orphaned projects (no prompt)
claude-ls prune --all --dry-run         # Preview what would be deleted
claude-ls prune --all --yes             # Skip confirmation prompt
claude-ls prune --claude-dir <path>

Prune removes:

• The session directory in ~/.claude/projects/
• The project entry in ~/.claude.json
• Matching lines in ~/.claude/history.jsonl
• Matching files in ~/.claude/usage-data/session-meta/

MIT