Tessyn

Tessyn is a background daemon that indexes Claude Code session files into a local SQLite database with full-text search. It watches for filesystem changes, parses JSONL in real time, and serves the indexed data over IPC and WebSocket. This gives you cross-session search, session history, and a CLI for developer workflow tools on top of your Claude Code sessions.

Prerequisites

• Node.js >= 22 (required)
• Claude Code CLI (optional, needed for title generation and run.send)
• macOS, Linux, or Windows
• Native build tools may be needed if prebuilt binaries aren't available for your platform (Xcode CLT on macOS, build-essential on Linux, MSVC Build Tools on Windows)

Quick Start

# Install globally (requires Node >= 22)
npm install -g tessyn

# Start the daemon
tessyn start

tessyn status
tessyn sessions list
tessyn search "auth bug"
tessyn search "refactor" --project my-project --role assistant
tessyn stop

Or from source:

git clone https://github.com/sapph1re/tessyn.git
cd tessyn
npm install
npm run build
npm install -g .

CLI Commands

Command	Description
tessyn start [--foreground]	Start the daemon (background by default, -f for foreground)
tessyn stop	Stop the daemon
tessyn status	Show daemon state, index stats, version
tessyn sessions list [--project <slug>] [--limit N]	List indexed sessions
tessyn sessions show <id> [--limit N]	Display session messages
tessyn search <query> [--project <slug>] [--role <role>]	Full-text search across all sessions
tessyn titles [--limit N]	Generate titles for untitled sessions (requires claude CLI)
tessyn watch	Stream daemon events in real-time
tessyn reindex	Rebuild the entire index from JSONL files
tessyn skills install	Install Claude Code skills (/recall, /sessions, /session-context)
tessyn skills install --uninstall	Remove installed skills

Claude Code Skills

Tessyn ships with skills (slash commands) for Claude Code. Install them once:

tessyn skills install

Then use them in any Claude Code session:

Skill	Description
/recall <query>	Search across all past sessions. Find previous conversations, implementations, and decisions.
/sessions	Browse session history across all projects. See recent sessions, filter by project.
/session-context <id>	Load a past session into the current conversation. Brings knowledge from a previous session without switching to it.

Skills require the Tessyn daemon to be running (tessyn start).

To remove installed skills: tessyn skills install --uninstall

How It Works

                         Tessyn Daemon
  Claude Code CLI      ┌──────────────────┐      GUI Frontends
  ┌──────────────┐     │ @parcel/watcher  │     ┌────────────┐
  │              │────→│ JSONL parser     │     │ Desktop    │
  │ Writes JSONL │     │ SQLite + FTS5    │←WS─→│ VS Code    │
  │ to disk      │←────│ RunManager       │     │ TUI        │
  │              │spawn│ IPC + WS servers │     └────────────┘
  └──────────────┘     └───────┬──────────┘
                               │IPC
                        ┌──────┴──────┐
                        │ tessyn CLI  │
                        └─────────────┘

1. Claude Code writes session data to ~/.claude/projects/<slug>/<id>.jsonl
2. Tessyn's watcher detects changes via native filesystem events
3. The indexer parses new JSONL lines incrementally (byte-offset checkpoints, no re-reading)
4. SQLite + FTS5 stores messages with full-text search, filtered by project/role
5. RunManager spawns and streams Claude sessions on behalf of GUI clients (run.send)
6. IPC server (Unix sockets / named pipes) serves the CLI
7. WebSocket server (localhost, token-authenticated) serves GUI frontends with real-time push notifications

JSONL files are the source of truth. Tessyn never writes to them. The SQLite database is a disposable index — tessyn reindex rebuilds it from scratch at any time.

Architecture

src/
├── daemon/       # Entry point, lifecycle, IPC + WebSocket servers
├── cli/          # Commander-based CLI, IPC client
├── assist/       # Claude API integration (title generation)
├── indexer/      # JSONL parser, checkpoint model, session discovery
├── db/           # SQLite, FTS5, migrations, prepared queries
├── watcher/      # @parcel/watcher, debounced change processing
├── protocol/     # JSON-RPC 2.0 types, handlers, event subscriptions
├── platform/     # Cross-platform paths, signals, installation
└── shared/       # Types, errors, logger

Cross-Platform

Tessyn runs on macOS, Windows, and Linux. CI tests on 4 targets:

Platform	IPC	File Watcher Backend
macOS ARM64	Unix domain socket	FSEvents
Linux x64	Unix domain socket	inotify
Linux ARM64	Unix domain socket	inotify
Windows x64	Named pipe	ReadDirectoryChangesW

Configuration

All paths are overridable via environment variables:

Variable	Default	Description
TESSYN_CLAUDE_DIR	~/.claude	Claude Code data directory
TESSYN_DATA_DIR	Platform-appropriate¹	Tessyn data directory (SQLite, logs)
TESSYN_DB_PATH	<data_dir>/tessyn.db	SQLite database path
TESSYN_SOCKET_PATH	/tmp/tessyn-<uid>.sock²	IPC socket path
TESSYN_WS_PORT	9833	WebSocket server port
TESSYN_LOG_LEVEL	info	Log level: debug, info, warn, error

¹ macOS: ~/Library/Application Support/tessyn/, Linux: ~/.local/share/tessyn/, Windows: %LOCALAPPDATA%\tessyn\Data\ ² Windows: \\.\pipe\tessyn-<username>

Development

npm install          # Install dependencies
npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm test             # All tests (unit + integration + E2E)
npm run test:unit    # Unit tests only
npm run test:watch   # Watch mode for unit tests
npm run lint         # ESLint

See docs/ for architecture, schema, protocol, and testing documentation.

Contributing

We use trunk-based development with master as the trunk. Merge (not rebase) to integrate changes.

Getting Started

External contributors: Fork the repo first, then clone your fork. Replace origin with upstream when pulling from the main repo.

Maintainers with write access: Clone the repo directly.

Workflow

# 1. Start from latest master
git switch master
git pull --ff-only origin master

# 2. Check for overlapping work
gh pr list   # Coordinate if someone is working on the same area

# 3. Create a branch
git switch -c <type>/<short-description>
# Types: feat/, fix/, refactor/, docs/, chore/, test/
# Examples: feat/title-generation, fix/socket-path-macos

# 4. Make changes, commit frequently

# 5. Before pushing — all must pass
npm run build && npm run lint && npm test

# 6. Before opening a PR — merge latest master
git fetch origin master
git merge origin/master   # Resolve any conflicts
npm test                  # Run tests again after merge

# 7. Push and open PR
git push -u origin <branch-name>
gh pr create

CI

All PRs are checked by GitHub Actions. All checks must pass before merging.

Check	Platforms
Lint + build	Linux x64
Unit tests	Linux x64, Linux ARM64, macOS ARM64, Windows x64
Integration tests	Linux x64, macOS ARM64, Windows x64
E2E tests	Linux x64, macOS ARM64

Where Things Go

• Code: src/, tests in test/
• Documentation: docs/ — update when architecture, schema, or protocol changes
• README: User-facing — update when CLI commands or configuration changes

Tech Stack

• TypeScript / Node.js (>=22) — daemon and CLI
• better-sqlite3 — synchronous SQLite with FTS5
• @parcel/watcher — native file watching (FSEvents, inotify, ReadDirectoryChangesW)
• ws — WebSocket server for GUI frontends
• commander — CLI framework
• env-paths — cross-platform data directories

License

MIT