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)

No API key: claudectl uses the Claude Code authentication you already have. No third-party packages — it is pure Python standard library.

Setup

Installing it as a command

pipx install claudectl     # or: pip install claudectl
claudectl

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

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.

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

pip install -e .        # or: pipx install .

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()

Windows shortcuts & taskbar pin

Desktop shortcut, taskbar pin and elevated launch

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.

Next steps