socrates

Socrates — "Know Your Self"

γνῶθι σεαυτόν — A session & settings manager for Claude Code

English | 한국어

When you run many Claude Code CLI sessions, two things get hard: (1) finding your way back to the session you were working in after a reboot, and (2) understanding what is actually configured across ~/.claude/ and per-project .claude/ directories (hooks, plugins, MCP servers, skills, agents). Socrates solves both.

Platform: macOS, Windows (Git Bash), and Linux. OS-specific tools (clipboard, file-open, stat/date, the Python interpreter) are detected at runtime. On Windows use Git Bash from Git for Windows; the interactive fzf picker is best confirmed in a real terminal.

socrates list: every session on the machine, aliased ones starred; Enter opens an action menu that copies --resume <UUID>.

Install

Option A — Plugin (recommended)

Inside Claude Code:

/plugin marketplace add beret21/socrates
/plugin install socrates@beret21

This registers the /socrates skill, and a SessionStart hook links the socrates / soc CLI into ~/.local/bin — so from your next session onward the CLI also works in a plain terminal.

Option B — Manual

git clone https://github.com/beret21/socrates.git
cd socrates && ./install.sh        # dependencies: brew install fzf jq

Neither method modifies your ~/.zshrc.

Usage

Inside a Claude session — name your session

/socrates:name my-task-name    # register a unique alias for the current session
/socrates:status               # show current session ID and alias

Aliases are unique across sessions — the tool exists to tell concurrent sessions apart (e.g. proposal-draft, proposal-hwpx, proposal-images in the same project folder), so registering a name another session already holds is rejected. Typed the wrong name? Just register again (overwrites, telling you what it replaced) or free a name with socrates unname.

(With the manual install the commands are /socrates-name and /socrates-status.)

In the terminal — socrates (short alias: soc)

Command	What it does
socrates / socrates list	fzf session picker. Enter → action menu; Ctrl-Y/Ctrl-O copy without leaving the picker (copy --resume / copy full cd … && claude --resume … / copy UUID / set alias / back); shortcuts: Ctrl-P narrows to the highlighted session's project, Ctrl-O cd+resume, Ctrl-Y UUID, Ctrl-N name. Ctrl-U/D scrolls the preview
socrates projects	two-stage navigation grouped by project (the storage folder is the group key — instant summary with session counts, ★ aliases, last activity); Enter opens that project's sessions, ESC goes back
socrates find <text>	full-text search across every session transcript on this machine — something the native picker cannot do. Matches open in the same picker, with matching snippets highlighted in the preview
socrates name [alias]	pick a session and set/update its alias
socrates unname	pick an alias and remove it (the session itself is untouched)
`socrates mem <text	id>`
socrates map	print the settings hierarchy, hooks, plugins, MCP servers, and skills/agents inventory
socrates report	generate a tabbed HTML dashboard (Overview / Projects / Sessions / Config X-ray / Anatomy (an annotated tree of your setup with live metrics) / Memory & Identity / Injection, with an EN/한국어 toggle) and open it. Memory & Identity shows how Claude identifies you (local ~/.claude.json account info) and every project's auto-memory files with their descriptions. The X-ray shows, per project, the settings layers and the full CLAUDE.md chain — every memory file a new session would load, walking from the filesystem root down to the project (official rule), with sizes and ancestor-folder warnings
socrates update	update everything from the terminal: plugin (skill + CLI) and relink — no Claude session needed. Manual installs do git pull
socrates doctor [--fix]	check the environment: dependencies, PATH, install links, registry integrity, orphaned aliases, version. --fix repairs missing/broken CLI links
socrates version	print the installed version and check GitHub for updates

socrates map: global settings, the CLAUDE.md chain for the current directory, and recent projects at a glance.