DEV Community

kaz
kaz

Posted on • Originally published at claunch.0xkaz.com

How I Solved Claude Code's Context Loss Problem with a Lightweight Session Manager

#claude #ai #productivity #cli

TL;DR

Image description

I was frustrated with Claude Code losing context every time I closed the terminal, especially when working across multiple projects. So I built claunch - a lightweight session manager that provides both direct and persistent Claude sessions per project.

  • Significant time savings
  • Two modes: Direct (default) & tmux-powered persistence
  • One-command session management
  • Open source & MIT licensed

The Problem

Claude Code is amazing for AI-assisted development, but it has one major pain point: context doesn't persist between sessions.

Here's what my typical workflow looked like:

$ claude
Human: I need help with this React app's authentication...
# Spend 10 minutes explaining project structure

# 1 hour later, switch to another project
$ cd ../api-project
$ claude  
Human: Working on database design for the API...
# Previous React context is completely lost

# Back to React project
$ cd ../react-project  
$ claude --resume [session-id]
# Can't remember the session ID, or it's invalid
Human: I need help with this React app's authentication...
# Spend another 10 minutes re-explaining everything
Enter fullscreen mode Exit fullscreen mode

The Hidden Cost

Each context rebuild takes 10-15 minutes, and switching between projects multiple times a day adds up to a significant amount of time lost to repetitive explanations.

Existing Solutions (And Why They Don't Work)

Before building claunch, I explored the existing options:

Official Approaches

  • Git Worktrees: Claude's recommended solution for multiple branches
  • Claude Squad: A terminal app for managing multiple Claude instances
  • --continue flag: Resumes the most recent conversation (single project only)

The Problems

  • Git Worktrees: Complex setup, massive disk usage
  • Claude Squad: Lacks simplicity, additional dependencies, learning curve
  • --continue: Useless for multi-project workflows

None of these felt right for my simple use case.

The Solution: claunch

claunch (claude + launch) is a lightweight session manager that gives you project-specific Claude sessions with optional persistence.

Core Concept

  1. Project-isolated Claude sessions
  2. Flexible execution modes (Direct or tmux-based)
  3. Zero-configuration interface

Usage 

$ cd ~/projects/react-app
$ claunch
# Direct Claude session (lightweight, default)

$ claunch --tmux
# Persistent Claude session (survives terminal crashes)

$ cd ~/projects/api-server  
$ claunch --tmux
# Separate persistent session for API project

# After system restart
$ cd ~/projects/react-app
$ claunch --tmux
# React conversation perfectly restored
Enter fullscreen mode Exit fullscreen mode

v0.0.4 Features 

# Direct mode (default) - Lightweight and fast
$ claunch
✓ Claude CLI session started for: nextjs-app

# tmux mode - Persistent sessions
$ claunch --tmux
🚀 Creating tmux session: nextjs-app
✓ Persistent Claude session started

# Session management
$ claunch list
📋 Active Claude sessions:
  - nextjs-app: sess-abc123def
  - api-server: sess-ghi456jkl

$ claunch clean
🧹 Cleaned up 2 orphaned session files
Enter fullscreen mode Exit fullscreen mode

Technical Implementation

The core is surprisingly simple:

#!/bin/bash
# Auto-detect project name
PROJECT=$(basename "$PWD")

# Create/attach tmux session
tmux new-session -As "claude-$PROJECT" \
  "claude --resume $(cat ~/.claude_session_$PROJECT)"
Enter fullscreen mode Exit fullscreen mode

Design Philosophy

  1. Follow Unix philosophy - Do one thing well
  2. Flexible by default - Direct mode for speed, tmux for persistence
  3. Minimal dependencies - Only requires bash and optionally tmux
  4. Zero configuration - Works immediately after install

Two Modes for Different Needs

Direct Mode (Default):

  • Lightweight, no dependencies
  • Fast startup
  • Perfect for quick sessions

tmux Mode (--tmux):

  • Persistent sessions
  • Background execution
  • Survives terminal crashes
  • Auto-installs tmux if needed

Results

Quantitative Impact

  • Projects managed: 12 concurrent projects
  • Context switching: 10 minutes → instant
  • Significant time savings

Qualitative Impact

  • No more repetitive explanations
  • Project-optimized AI conversations
  • Improved workflow continuity

Installation & Usage

Install 

bash <(curl -s https://raw.githubusercontent.com/0xkaz/claunch/main/install.sh)
Enter fullscreen mode Exit fullscreen mode

Basic Commands 

# Run in any project directory
$ claunch

# List active sessions  
$ claunch list

# Clean up old session files
$ claunch clean
Enter fullscreen mode Exit fullscreen mode

Community Response

The response has been overwhelmingly positive. Developers appreciate the Unix philosophy approach - solving one problem really well with minimal complexity.

Future Plans

  • Session sharing capabilities
  • Backup/restore functionality
  • Template system for common setups

Open Source

claunch is open source (MIT license) and welcomes contributions:

  • Bug reports
  • Feature requests
  • Pull requests
  • Documentation improvements

Conclusion

claunch exemplifies "small tools, big impact." It's a simple solution that dramatically improves the daily development experience.

Sometimes the best solutions aren't the most complex ones - they're the ones that solve a real problem elegantly.

Links

Give it a try and let me know what you think!

What's your biggest pain point with AI coding assistants? I'd love to hear about other workflow improvements you've made.

Top comments (1)

Collapse
 
boldfaceline profile image
Andrew Teeples •

Session persistence is a good baseline. But I've been running a different experiment: what if you don't preserve the full session, but extract and accumulate the state across sessions?

Built three extraction layers and measured each against what I actually carried between sessions:

  • Heuristic (file paths, git actions, URLs): 4% overlap with what mattered
  • Model-assisted (small LLM extracts context): 16% overlap
  • Manual curation (30 seconds writing "what was I thinking"): fills the remaining 84%

The 84% gap is interpretive context — why you're doing something, what you're avoiding, cross-session patterns. No extraction method reaches it because it's not in the transcript.

Your approach preserves the conversation itself, which is valuable for single long-running tasks. The accumulation approach trades conversation history for compressed state, which works better across many short sessions. Different trade-offs for different workflows.

Wrote up the full findings if you're interested: boldfaceline.com/posts/four-percent

To answer your question about pain points with AI coding assistants: the biggest one isn't forgetting. It's forgetting selectively — losing the interpretation while keeping the facts.