Claudes Code, terminals, and other CLI friends in your browser. Speak with the dead, jump to your phone, and lots more

Run multiple terminals in tabs | Detach & reattach sessions | Browse Claude Code history | What if tmux and Claude fell in love?

• Multi-tab terminal sessions — Run shell, Claude Code, and Codex in parallel tabs
• Split panes — Divide any tab into independent terminal panes (horizontal/vertical)
• Detach/reattach — Background terminals persist across browser sessions
• Search & browse — Filter Claude sessions by project, date, or content
• Speak with the dead — Invoke the spirits of ancient Claudes and ask them what they were thinking
• Keep it tidy — AI (or your pedantic self) names, summarizes, and organizes
• Dark/light themes — Are we savages?
• Keyboard-driven — tmux-style prefix shortcuts for power users

# Clone the repository
git clone https://github.com/danshapiro/freshell.git
cd freshell

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env and set AUTH_TOKEN to a secure random value

# Build and run
npm run serve

Open http://localhost:3001/?token=YOUR_AUTH_TOKEN

Note: WSL is optional on Windows. The app defaults to cmd.exe for terminals. Set WINDOWS_SHELL=wsl or WINDOWS_SHELL=powershell to change. WSL is only needed if your Claude sessions live inside the Linux filesystem.

# Install build dependencies
sudo apt update
sudo apt install -y build-essential python3

# Install Node.js (via NodeSource)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

# Clone
git clone https://github.com/yourusername/freshell.git
cd freshell

# Install dependencies
npm install

# Create environment file
cp .env.example .env

Edit .env with your configuration:

# Required: secure random token (min 16 characters)
AUTH_TOKEN=your-secure-random-token-here

# Optional: server port (default 3001)
PORT=3001

# Windows only: shell type (cmd, powershell, or wsl). Default: cmd
# WINDOWS_SHELL=cmd

# Windows/WSL: path to Claude home (use WSL path if using WSL)
CLAUDE_HOME=\\wsl$\Ubuntu\home\your-user\.claude
WSL_DISTRO=Ubuntu

# Optional: Gemini API key for AI summaries
GOOGLE_GENERATIVE_AI_API_KEY=your-api-key

Run the client and server with hot reload:

npm run dev

Or run them separately:

# Terminal 1 - Server
npm run dev:server

# Terminal 2 - Client
npm run dev:client

# Build and run (recommended)
npm run serve

Or build and run separately:

npm run build
npm start

Access the app at http://localhost:3001/?token=YOUR_AUTH_TOKEN

freshell uses a tmux-style prefix system. Press Ctrl+B followed by a command key:

If your Claude Code sessions live inside WSL at ~/.claude, configure access from Windows:

WINDOWS_SHELL=wsl
CLAUDE_HOME=\\wsl$\Ubuntu\home\your-username\.claude
WSL_DISTRO=Ubuntu

The server will watch CLAUDE_HOME/projects/**/sessions/*.jsonl for new sessions.

• AUTH_TOKEN is mandatory — The server refuses to start without it
• API authentication — All /api/* routes require x-auth-token header
• WebSocket handshake — Connections must send a valid token in the hello message
• Origin restriction — WebSocket connections limited to allowed origins

# Run all tests
npm test

# Run with UI
npm run test:ui

# Run specific test suites
npm run test:unit          # Unit tests only
npm run test:server        # Server tests only
npm run test:client        # Client tests only
npm run test:coverage      # With coverage report

• Frontend: React 18, Redux Toolkit, Tailwind CSS, xterm.js
• Backend: Express, WebSocket (ws), node-pty
• Build: Vite, TypeScript
• AI: Vercel AI SDK with Google Gemini

freshell/
├── src/                  # Frontend source
│   ├── components/       # React components
│   ├── store/            # Redux store & slices
│   ├── lib/              # Utilities & API client
│   └── hooks/            # Custom React hooks
├── server/               # Backend source
│   ├── index.ts          # Server entry point
│   ├── ws-handler.ts     # WebSocket handling
│   └── claude-session.ts # Session indexer
├── test/                 # Test suites
└── dist/                 # Build output

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

MIT License — see LICENSE for details.

Made with terminals and caffeine