archeus

_{Formerly claudectl. Everything migrates on first run — settings, memory graphs and per-project state. Nothing is deleted.
The name is Paracelsus' term for the force that keeps living matter coherent. Not Arceus, which is Nintendo's and spelled the other way round.}

The memory and workspace layer for AI coding agents.
Persistent per-project memory, every session you have ever had, and control over what the next one costs. Works with Claude Code, OpenAI Codex and pi.

🌐 claudectl.space  ·  📖 Full documentation → docs.claudectl.space
_{Everything below is the short version. Every feature, key binding and file is documented in detail on the docs site.
PyPI · Blog · FAQ · LinkedIn · dev.to}

What problem does this solve?

A coding agent 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. That is not a Claude Code problem; it is what every agent that runs in a terminal has in common.

archeus sits in front of the agent 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.

Claude Code is the agent it drives today. 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 archeus     # or: pip install archeus
archeus

There is nothing to build and no dependencies to install. npx archeus runs it without installing it first — that package is a launcher, which installs archeus with pipx or pip when it cannot find it. To run it from a checkout instead:

git clone https://github.com/babarmuhammad/archeus.git
cd archeus
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/archeus
/plugin install archeus@archeus

→ 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: 32 palettes, 8 skins and 4 themed worlds — a skin changes the shape of the app, not just its colours. See them →}

Why archeus

• 🧠 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 the agent touches those files, and an optional per-prompt hook that injects just the subgraph relevant to what you asked. It also learns: durable lessons (fixes, decisions, preferences) distilled from transcripts, human-reviewed, injected when relevant, decayed when stale.
• 📦 Workspace, not chats — browse, search, tag, fork, resume and archive every session across every project and account, over an animated dependency graph that opens at the project level and drills down to single files.
• 🩺 It removes the friction you actually hit — pre-launch health checks, context-loss insurance after /compact, permission-fatigue killer, token-burn advisor, daily usage tracking, and the right subagents suggested per project from local signals. Zero runtime dependencies: pure Python standard library, using the agent auth you already have.

How archeus saves tokens

Without archeus, a big project either starves the agent (no context) or floods it (a huge CLAUDE.md loaded every message). archeus 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

Where this is going

Half has arrived: a session can be routed at any endpoint serving POST /v1/messages — local Ollama, llama.cpp, vLLM, OpenRouter — with agents, skills, hooks and MCP intact. Driving another harness is the other half and a long-term goal, not a feature: Claude Code is the first surface, not the boundary.

Documentation

The full manual lives at docs.claudectl.space.

Product pages — Features · Compare · FAQ · Download · Changelog — are on claudectl.space.

Credits

archeus 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 archeus 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. Free, and always will be — you can support it on Ko-fi if you like: voluntary, and it buys nothing. Privacy · Terms