claudectl

The workspace layer for Claude Code.
Your projects stop being a stream of chats and start being workspaces — with memory, history, and per-project launch control.

📖 Full documentation → babarmuhammad.github.io/claudectl
_{Everything below is the short version. Every feature, key binding and file is documented in detail on the docs site.}

What problem does this solve?

Claude Code is excellent inside a session and forgetful between them. Every new session starts from nothing, your old sessions are hard to find, and the only way to give the agent context is a CLAUDE.md that grows until it costs more than it's worth.

claudectl sits in front of Claude Code and fixes that. Pick a project, see every session you've ever had in it, and launch with the model, effort, permissions and context you meant. Underneath, it maintains a semantic memory of the codebase and injects only the part relevant to what you just asked.

It is a terminal UI and a desktop GUI over the same engine — use whichever you prefer, they do the same things.

Quickstart

pipx install claudectl     # or: pip install claudectl
claudectl

There is nothing to build and no dependencies to install. To run it from a checkout instead:

git clone https://github.com/babarmuhammad/claudectl.git
cd claudectl
python claude-sessions.py          # terminal UI
python claude-sessions.py --gui    # desktop GUI

Requires Python 3.10+ and the Claude Code CLI (auto-detected on PATH or at ~/.local/bin/). No API key — it uses the Claude Code auth you already have. No third-party packages.

It also ships as a Claude Code plugin, if you'd rather stay inside the session:

/plugin marketplace add babarmuhammad/claudectl
/plugin install claudectl@claudectl

→ Full install guide

What it looks like

Every session, every project. Search, tag, fork, resume, archive, export — across multiple Claude accounts at once.	Memory Claude built about your code. Entities, relations and lessons, with the token cost of every block shown before you spend it.
Where the tokens went. Per day, per project, per account, per model — read from your own transcripts, not an API.	Claude Code itself, made visible. Which skills and plugins you actually use, what is on disk, and a typed editor for every account's settings.

The terminal UI is the same tool, keyboard-first:

_{The architecture graph — every module and its dependencies, expandable down to single files (Python · C/C++ · C# · JS/TS).}

_{Also: 29 palettes, 7 skins and 4 themed worlds — a skin changes the shape of the app, not just its colours. See them →}

Why claudectl

• 🧠 Intelligent memory, not a memory dump — task-scoped, token-budgeted injection at the launcher: a micro-index always on (≤250 tok), per-module detail loaded only when Claude touches those files, and an optional per-prompt hook that injects just the subgraph relevant to what you asked.
• 📚 It learns from every session — durable lessons (fixes, decisions, preferences) distilled from transcripts, human-reviewed, injected when relevant, decayed when stale.
• 🕸️ See your architecture — an animated, expandable dependency graph that opens at the project level and drills down to single files.
• 🩺 Auto-solves common Claude Code pain — pre-launch health checks, context-loss insurance after /compact, permission-fatigue killer, token-burn advisor, daily usage tracking.
• 🤖 Adaptive agents — the right subagents suggested (or auto-applied) per project from local signals.
• 📦 Workspace, not chats — browse, search, tag, fork, resume and archive every Claude Code session across every project and account.
• ⚡ Zero runtime dependencies — pure Python standard library; uses your existing Claude Code auth.

How claudectl saves tokens

Without claudectl, a big project either starves the agent (no context) or floods it (a huge CLAUDE.md loaded every message). claudectl spends the minimum tokens for the maximum relevant context:

• Flat always-on cost — the CLAUDE.md block is a ≤250-token index, not a full dump; it does not grow as the codebase grows.
• On-demand detail — per-module knowledge lives in path-scoped .claude/rules/, so nothing is paid for until it's relevant.
• Task-scoped injection — the optional prompt hook injects only the subgraph your prompt actually needs (budgeted, default ≤600 tok).
• No stale weight — superseded facts are invalidated, dead entities evicted.
• Cheaper model for the grunt work — Plan→Execute runs the expensive model once for the plan and a cheap (or free) one for execution.

→ How the token economy works

Documentation

The full manual lives at babarmuhammad.github.io/claudectl.

Credits

claudectl is built on ideas from the wider Claude Code ecosystem — cognee and Aider's repo-map behind the memory graph, Anthropic's code-review plugin behind claudectl review, claude-mem behind recent-work memory, OmniRoute behind free execution, and VoltAgent's subagent catalog behind the agent library. Every one is credited, with links, on the Credits page.

License

MIT — see LICENSE.