Skip to content

Install

Requirements

  • Python 3.10+
  • Windows, macOS or Linux
  • Claude Code CLI installed (auto-detected at ~/.local/bin/ or on PATH; overridable in Settings)
  • Any text editor — Notepad++ / VS Code / $EDITOR are auto-detected (overridable in Settings)

Setup

Clone and run

git clone https://github.com/babarmuhammad/claudectl.git
cd claudectl
python claude-sessions.py

There is nothing to build and no dependencies to install. On Windows you can double-click Open Repo cmd.bat instead of using a terminal.

Installing it as a command

pipx install claudectl     # or: pip install claudectl
claudectl

To put the command on your PATH from a checkout instead — for development, or to run an unreleased change:

pip install -e .        # or: pipx install .

That gives you claudectl, claudectl --gui, claudectl review, claudectl recall "<topic>" and claudectl statusline from anywhere.

Inside a Claude Code session

claudectl also ships as a Claude Code plugin, which puts its three most useful commands and its eight skills inside the session itself:

/plugin marketplace add babarmuhammad/claudectl
/plugin install claudectl@claudectl
/claudectl:recall <topic> This project's task-relevant memory, scored locally — no model call
/claudectl:status Memory age, repositories and worktrees, health checks
/claudectl:review Review the current diff against this project's own learned conventions

The commands shell out to the claudectl CLI, so install that too; the skills work on their own. The plugin deliberately ships no hooks — claudectl's own hook manager owns those, and two owners for one settings.json entry means the recall hook runs twice per prompt.

GUI setup

The desktop GUI needs no extra dependencies for the Edge/browser shells. For the native window install PyQt6 (optional):

pip install PyQt6 PyQt6-WebEngine

Start it with:

python claude-sessions.py --gui   # from the checkout
claudectl --gui                   # after `pip install -e .`

gui_shell in Settings picks the window: auto (Qt → Edge app window → browser), qt, edge, or browser. The bottom-left TUI/GUI toggle (or the ui_mode setting) selects which interface starts by default; --tui / --gui always override.

Desktop shortcut with the GUI icon — the GUI has its own icon (claudectl-gui.ico, regenerate with py tools/make_gui_icon.py). pythonw.exe runs it without a console window:

$shell = New-Object -ComObject WScript.Shell
$lnk = $shell.CreateShortcut("$env:USERPROFILE\Desktop\claudectl GUI.lnk")
$lnk.TargetPath       = "$env:LOCALAPPDATA\Programs\Python\Python310\pythonw.exe"
$lnk.Arguments        = "`"$PWD\claude-sessions.py`" --gui"
$lnk.WorkingDirectory = "$PWD"
$lnk.IconLocation     = "$PWD\claudectl-gui.ico, 0"
$lnk.Save()
Optional: Desktop shortcut & taskbar pin **Desktop shortcut** — right-click `Open Repo cmd.bat` → **Send to** → **Desktop (create shortcut)**. **Pin to taskbar (Windows 11)** — Windows 11 can't pin `.bat` shortcuts directly; the shortcut must point to `cmd.exe`. Run this once in PowerShell from the repo folder: 
$shell = New-Object -ComObject WScript.Shell
$lnk = $shell.CreateShortcut("$env:USERPROFILE\Desktop\Open Repo Claude.lnk")
$lnk.TargetPath       = "C:\Windows\System32\cmd.exe"
$lnk.Arguments        = "/c `"$PWD\Open Repo cmd.bat`""
$lnk.WorkingDirectory = "$PWD"
$lnk.IconLocation     = "$PWD\claudectl.ico, 0"
$lnk.Save()
Then right-click the Desktop shortcut → **Pin to taskbar**. **Elevated shortcut, no repeated UAC prompt** — if `claude.exe` or your project paths need admin rights, a plain "Run as administrator" shortcut checkbox triggers a UAC prompt on every launch. To elevate once and skip the prompt afterward, register a Scheduled Task that already runs at highest privilege, then point the shortcut at `schtasks /run`: 
# 1) register the task (one-time)
$action    = New-ScheduledTaskAction -Execute "C:\Users\<you>\AppData\Local\Microsoft\WindowsApps\wt.exe" -Argument '-d "<repo>" powershell -Command "& ''<repo>\Open Repo cmd.bat''"' -WorkingDirectory "<repo>"
$principal = New-ScheduledTaskPrincipal -UserId $env:USERNAME -RunLevel Highest -LogonType Interactive
$settings  = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -StartWhenAvailable
Register-ScheduledTask -TaskName "ClaudeCtl" -Action $action -Principal $principal -Settings $settings -Force

# 2) point the shortcut at the task instead of launching directly
$shell = New-Object -ComObject WScript.Shell
$lnk = $shell.CreateShortcut("$env:USERPROFILE\Desktop\claudectl.lnk")
$lnk.TargetPath       = "C:\Windows\System32\schtasks.exe"
$lnk.Arguments        = '/run /tn "ClaudeCtl"'
$lnk.WorkingDirectory = "<repo>"
$lnk.IconLocation     = "<repo>\claudectl.ico, 0"
$lnk.Save()
Leave the shortcut's own **"Run as administrator"** checkbox unticked — `schtasks.exe` itself doesn't need to be elevated, only the task it triggers. Launching via `wt.exe` (instead of `cmd.exe`/`powershell.exe` directly) also avoids the legacy-conhost fallback that elevated console apps can trigger, which otherwise makes the TUI render with broken colors/box-drawing under UAC.

Installing the agent library

The ⚙ Agents screen reads ~/.claude/claudectl-agents/<category>/*.md. To bulk-install the awesome-claude-code-subagents catalog (154 agents, mirrored by category), run this PowerShell snippet once:

The agent catalog is created and maintained by VoltAgent — awesome-claude-code-subagents. claudectl only mirrors it into the library; all credit for the agents goes to the original authors. Please refer to that repository for its license and contribution terms.

$repo = 'https://api.github.com/repos/VoltAgent/awesome-claude-code-subagents/contents/categories'
$raw  = 'https://raw.githubusercontent.com/VoltAgent/awesome-claude-code-subagents/main/categories'
$lib  = "$env:USERPROFILE\.claude\claudectl-agents"
foreach ($cat in (Invoke-RestMethod $repo | Where-Object { $_.type -eq 'dir' }).name) {
    $dir = Join-Path $lib $cat
    New-Item -ItemType Directory -Force $dir | Out-Null
    foreach ($f in (Invoke-RestMethod "$repo/$cat") | Where-Object { $_.name -like '*.md' -and $_.name -ne 'README.md' }) {
        Invoke-WebRequest "$raw/$cat/$($f.name)" -OutFile (Join-Path $dir $f.name)
    }
    Write-Host "$cat done"
}

Install a single agent directly into the library (e.g. into 09-meta-orchestration):

curl -sL https://raw.githubusercontent.com/VoltAgent/awesome-claude-code-subagents/main/categories/09-meta-orchestration/agent-installer.md \
  -o "$USERPROFILE/.claude/claudectl-agents/09-meta-orchestration/agent-installer.md"

These land in the library (not ~/.claude/agents/), so they don't bloat every Claude session — claudectl copies only the ones you select for a project into that project's .claude/agents/ (g in the sessions menu).