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
The terminal UI is the same tool, keyboard-first:
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.
| |
|---|
| Getting started | what it is, the three surfaces, where to go next |
| Installation | pipx, pip, checkout, plugin, GUI window, Windows shortcuts |
| Quickstart | install to first session in five minutes |
| Command line | every command, for scripts and hooks |
| Terminal UI | every screen and every key binding |
| Desktop app | the same workspace as a local app, plus the theme system |
| Configuration | every file archeus reads and writes, and where |
| Project memory | the three injection surfaces, lessons, recall |
| Architecture graph | the interactive dependency view |
| Usage & cost | measuring and cutting the per-turn cost |
| API reference | the local HTTP API the GUI is built on |
| Troubleshooting | when something does not work |
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
