🔖 Claude Sessions Manager

Your daily starting point for Claude Code.
Pick up any conversation right where you left off, no re-explaining the project, no lost context.

🇺🇸 English · 🇧🇷 Português · 🇪🇸 Español · 🇯🇵 日本語 · 🇨🇳 简体中文 · 🇰🇷 한국어 · 🇩🇪 Deutsch

💡 Why use it

Every project has a hidden cost: reheating context. Every time you open Claude, you lose time:

• 🔁 Re-explaining the architecture
• 📍 Pointing out where you stopped
• 📂 Listing the important files
• 🧠 Realigning what was in progress

That's 15–30 minutes just to start being productive. And when the terminal closes, the context Claude just built is gone.

✨ Good news: Claude Code already saves every conversation for you to resume.

😩 The problem: finding the right conversation among dozens of auto-generated codes.

That's what this project solves. In 4 steps:

1. 🏁 Open the dashboard
2. 🎯 Find the right conversation
3. 📋 Click and the command is already in your clipboard
4. 💻 Paste in the terminal and pick up where you left off

Resuming costs seconds. Starting over costs hours.

✨ Features

📦 Installation

1️⃣ Clone the repository

git clone https://github.com/krugerrgabriel/claude-sessions-manager.git
cd claude-sessions-manager

2️⃣ Run the installer

sudo ./install.sh

The installer takes care of everything: it installs what's missing, copies the files, adjusts permissions, and configures the web server. Finishes in seconds.

3️⃣ Open it in your browser

Two ways, pick whichever you prefer:

🖥️ Directly via URL: http://localhost/claude-sessions/

⌨️ Or from the terminal:

claude-sessions

or

claude-sessions-manager

The installer creates that command automatically: it opens the dashboard in your default browser.

Done. 🎉

💡 Single prerequisite: any Linux with apt (Ubuntu, Debian, Mint, Pop!_OS, etc.) and sudo.

⚙️ Advanced configuration

Only use these if you need to, everything works out of the box.

sudo INSTALL_DIR=/opt/claude-sessions-manager URL_PATH=/dashboard ./install.sh

Then open http://localhost/dashboard/.

sudo PROJECTS_DIR=/alternative/path/.claude/projects ./install.sh

sudo ./uninstall.sh           # keeps your notes (names, favorites, descriptions)
sudo ./uninstall.sh --purge   # removes everything, including your notes

⌨️ Shortcuts

🏗️ How it works under the hood

┌─────────────────────────────────────────────────────────────────┐
│                        Browser (you)                            │
└───────────────┬─────────────────────────────────┬───────────────┘
                │ HTML/CSS/JS                      │ fetch /api/*
                ▼                                  ▼
┌────────────────────────┐          ┌────────────────────────────┐
│   Apache2 (static)     │          │  mod_wsgi → app.wsgi (py)  │
└────────────────────────┘          └──────────────┬─────────────┘
                                                   │ read/write
                                                   ▼
            ┌─────────────────────────────────────────────────────┐
            │  ~/.claude/projects/*/*.jsonl    (your sessions)    │
            │  data/metadata.json              (your notes)        │
            │  cache/sessions.json             (internal cache)    │
            └─────────────────────────────────────────────────────┘

Stack

Repository layout

claude-sessions-manager/
├── index.html       ← UI and SVG icons
├── style.css        ← design system (dark theme)
├── app.js           ← rendering and API logic
├── app.wsgi         ← Python backend
├── i18n/            ← translation dictionaries (one JSON per language)
├── VERSION          ← current version, synced from the latest release
├── install.sh       ← installer
├── uninstall.sh     ← uninstaller
├── README.md        ← you are here
├── .gitignore       ← ignores generated data
├── data/            ← (generated) your notes
└── cache/           ← (generated) internal cache

🔒 Security

• The backend runs as you, not as www-data. It reads your sessions without a global chmod.
• The API only accepts IDs in UUID format (no path traversal).
• Permanent deletion requires double confirmation in the frontend.
• Serves only on http://localhost by default. Do not expose it to the internet without authentication.

🛠️ Developing

No build step. Edit and refresh the page.

# Force mod_wsgi to reload after changing the backend
sudo touch /var/www/html/claude-sessions/app.wsgi

# Tail the logs
sudo tail -f /var/log/apache2/error.log

# Clear the internal cache (after changing parsing logic)
rm -f /var/www/html/claude-sessions/cache/sessions.json

🐛 Troubleshooting

sudo tail -20 /var/log/apache2/error.log

Common causes:

• ~/.claude/projects/ doesn't exist yet, run Claude Code at least once
• mod_wsgi isn't enabled: sudo a2enmod wsgi && sudo systemctl reload apache2

The backend needs to run as the file owner. Check:

grep WSGIDaemonProcess /etc/apache2/conf-available/claude-sessions.conf

The line must include user=YOUR_USERNAME.

Only main (resumable) sessions are listed. Internal sub-agent conversations are intentionally ignored.

sudo touch /var/www/html/claude-sessions/app.wsgi
sudo systemctl reload apache2

In the browser: Ctrl+Shift+R to bust the browser cache.

🤝 Contributing

PRs welcome. Before submitting:

• Keep zero dependencies (no pip, no npm)
• Follow the design system in style.css (semantic CSS variables)
• New icons: add a <symbol> to the SVG sprite in index.html (Lucide-style, stroke 2, 24×24)

📜 License

MIT, do whatever you want.

Made with vim and coffee.