go-thinkt

README

🧠 thinkt

thinkt is a platform for exploring, analyzing, and sharing conversation traces from AI coding assistants. You can learn more about us at wethinkt.com.

There are many local agentic coding environments such as Claude Code, Kimi Code, and Gemini CLI. As you use them, session data is written locally. thinkt unlocks that conversation data for you.

You can use thinkt to...

• Explore and search the conversation traces with a CLI, TUI, or webapp
• Analyze these conversations for understanding and governance
• Share these with your tooling and LLMs via an OpenAPI HTTP server and MCP server

All of these LLM assistant Sources have similar structures and use common machinery such as JSONL file:

• Projects located in local folders, which hold many:
  • Sessions that have many conversation Turns, which each have:
    • one User Input
      • multiple Tool Calls and Tool Result
      • multiple Thinking blocks
    • one LLM Output

We have a common thinkt interface to enable uniform access to various Sources. We maintain a library of implementations and currently support:

• Claude Code from Anthropic
• Kimi Code from Moonshot
• Gemini CLI from Google
• Copilot CLI from GitHub
• Codex CLI from OpenAI
• Qwen Code from Alibaba

All of this structured data is exposed to you to easily navigate:

• CLI command-line tool for quick listing and tooling
• TUI for working in the terminal
• WebApp for working in the browser
• MCP Server for LLMs access to tools

For developers, we have an OpenAPI server and a the ts-thinkt TypeScript package. Gophers, right now most of the implementation is in package internal; stabilizing a public package is on our roadmap.

Integrated in thinkt is an indexer to speed up searches and other operations, as well as support for semantic search local inferencing support

For beyond local deployments, we also have thinkt-exporter and thinkt-collector tools.

User Guide

Features

• Interactive TUI: Navigate projects, sessions, and conversation content with a keyboard-driven terminal interface
• Multi-Source Support: Works with Claude Code (~/.claude), Kimi Code (~/.kimi), Gemini CLI (~/.gemini), Copilot CLI (~/.copilot), Codex CLI (~/.codex), and Qwen Code (~/.qwen) — sessions from all sources are shown together
• Tree View: Browse projects in a collapsible tree grouped by directory, or switch to a flat list
• Agent Teams: Inspect multi-agent teams (Claude Code), including members, tasks, and messages
• Analytics: Token usage, tool frequency, word analysis, activity timelines via thinkt-indexer
• Local Summarization: Generate per-session summaries, classify thinking blocks, and suggest shareable tags with local models via thinkt-indexer summarize
• Prompt Extraction: Generate timestamped logs of user prompts in markdown, JSON, or plain text
• MCP Server: Model Context Protocol integration for use with AI assistants
• REST API: HTTP server for programmatic access
• Web Interface: Full webapp for visual trace exploration via thinkt web
• Lite Webapp: Lightweight debug interface with i18n (EN/ES/中文), connection status, and "open-in" buttons
• Trace Collector: Push-based trace aggregation from multiple machines via thinkt collect
• Trace Exporter: Watch local sessions and ship to a remote collector via thinkt export
• Themes: Customizable color themes with interactive theme builder
• App Management: Configure open-in apps and default terminal via thinkt apps

Installation

Homebrew

brew install --cask wethinkt/tap/thinkt

Go

go install github.com/wethinkt/go-thinkt/cmd/thinkt@latest

From Source

git clone --recurse-submodules https://github.com/wethinkt/go-thinkt.git
cd go-thinkt
task dev-deps
task build

Docker

Multi-platform Docker images are available for linux/amd64 and linux/arm64:

docker pull ghcr.io/wethinkt/thinkt:latest

The container user's home directory is /data, so default paths like ~/.claude resolve to /data/.claude. Simply bind-mount your session directories:

# Run the HTTP server
docker run -p 8784:8784 \
  -v ~/.claude:/data/.claude:ro \
  -v ~/.kimi:/data/.kimi:ro \
  -v ~/.codex:/data/.codex:ro \
  ghcr.io/wethinkt/thinkt:latest server --host 0.0.0.0

# Run any command
docker run \
  -v ~/.claude:/data/.claude:ro \
  -v ~/.codex:/data/.codex:ro \
  ghcr.io/wethinkt/thinkt:latest projects

# Show help
docker run ghcr.io/wethinkt/thinkt:latest --help

Quick Start

# First-time setup
thinkt setup

# Launch interactive TUI (default)
thinkt

# Get help
thinkt help                # Overview of all commands
thinkt help cheat          # Visual command tree
thinkt help cheat --json   # Machine-readable command tree
thinkt help llms           # Usage guide for AI assistants
thinkt help <command>      # Help for a specific command

# List available sources
thinkt sources list

# Browse projects
thinkt projects
thinkt projects --short
thinkt projects tree

# View sessions
thinkt sessions list
thinkt sessions view
thinkt sessions resolve -p ./myproject <session-id>

# List agent teams
thinkt teams

# Open the web interface
thinkt web

# Start HTTP server without opening browser
thinkt server --no-open

# Export traces to a collector
thinkt export --forward

# Start a trace collector
thinkt collect --token mytoken

# Debug logging
thinkt tui --log /tmp/thinkt-debug.log

Commands

Command	Description
thinkt	Launch interactive TUI (default)
thinkt setup	Scan for AI session sources and configure thinkt
thinkt help	Overview of all commands and help topics
thinkt help cheat	Visual command tree (--json for machine-readable)
thinkt help llms	Usage guide for LLMs and AI assistants
thinkt tui	Launch interactive TUI
thinkt sources	List available sources (claude, kimi, gemini, copilot, codex, qwen)
thinkt sources status	Show detailed source status
thinkt projects	List all projects (detailed columns)
thinkt projects --short	List project paths only
thinkt projects tree	Tree view grouped by parent directory
thinkt projects summary	Detailed project info
thinkt sessions list	List sessions in a project
thinkt sessions view	View session in terminal
thinkt sessions resolve	Resolve a session query to its canonical path
thinkt sessions copy	Copy a known session to another path
thinkt sessions delete	Delete a known session (with confirmation)
thinkt teams	List agent teams (Claude Code)
thinkt teams list	Same as above
thinkt prompts extract	Extract prompts to markdown/JSON
thinkt export	Export traces to a remote collector
thinkt export --forward	Continuous watch mode
thinkt export --flush	Flush the disk buffer
thinkt agents	List active agents (local and remote)
thinkt agents --local	Local agents only
thinkt agents follow <id>	Live-tail an agent's conversation
thinkt collect	Start trace collector server (port 8785)
thinkt collect --token	Collector with bearer token auth
thinkt web	Open web interface in browser
thinkt web lite	Open lightweight debug webapp
thinkt apps	List configured open-in apps
thinkt apps enable/disable	Enable or disable an app
thinkt apps set-terminal	Set the default terminal app
thinkt search	Search for text across indexed sessions
thinkt semantic search	Search sessions by meaning using on-device embeddings
thinkt embeddings	Manage embedding model, storage, and sync
thinkt theme	Browse and manage TUI themes
thinkt theme list	List all available themes
thinkt theme set <name>	Set the active theme
thinkt theme import	Import iTerm2 color scheme
thinkt theme builder	Interactive theme editor

Indexer (DuckDB-Powered)

The thinkt-indexer provides fast, searchable storage for your conversation traces. Indexer commands are accessible through the main thinkt CLI as well as via the thinkt-indexer binary directly:

# Start the indexer server (syncs, watches for changes, and serves RPC)
thinkt indexer start

# Search across indexed sessions (case-insensitive by default)
thinkt search "authentication"

# Case-sensitive or regex search
thinkt search "AuthManager" --case-sensitive
thinkt search --regex "func\s+Test\w+"

# Show usage statistics
thinkt indexer stats

# Manage local summarization and tags
thinkt-indexer summarize status
thinkt-indexer summarize sync
thinkt-indexer summarize tags "fix sync gate races and add sharing tags"

# Manage embeddings
thinkt embeddings list
thinkt embeddings status
thinkt embeddings model

# Or use thinkt-indexer directly
thinkt-indexer sync
thinkt-indexer search "authentication"
thinkt-indexer stats
thinkt-indexer summarize tags --json "duckdb sync gate sharing flow"

thinkt-indexer summarize uses local generative models for three related tasks:

• entry-level summary/classification of thinking blocks
• session-level summaries
• shareable tag suggestions for discovery and sharing workflows

The summarization prompts are embedded from internal/indexer/summarize/prompts/ so they can be tuned without editing Go string literals.

Semantic Search

On-device semantic search uses on-device embedding models (nomic-embed-text-v1.5 by default) to find sessions by meaning, not just keywords. The model is configurable via thinkt embeddings model.

# Enable semantic search (downloads model on first use)
thinkt-indexer semantic enable

# Search by meaning
thinkt semantic search "database migration strategy"

# Filter by project or source
thinkt semantic search "error handling" --project my-app --source claude

# Diversity mode spreads results across different sessions
thinkt semantic search "testing patterns" --diversity

# Check embedding status
thinkt embeddings status
thinkt embeddings status --json

# Or use thinkt-indexer directly
thinkt-indexer semantic search "database migration strategy"
thinkt-indexer semantic stats

# Disable semantic search
thinkt-indexer semantic disable

Semantic search is disabled by default. Enable it with thinkt-indexer semantic enable — the embedding model is downloaded automatically on first sync.

Indexer data is stored in ~/.thinkt/dbs/indexer.duckdb (metadata) and ~/.thinkt/embeddings/ (per-model embedding databases). Set THINKT_HOME to override ~/.thinkt.

TUI Keyboard Shortcuts

The interactive TUI uses a navigation stack. ESC goes back to the previous screen; q or ctrl+c exits the app.

Project Picker:

Key	Action
enter	Select project / toggle directory
/	Search/filter
t	Toggle tree view / flat list
space	Toggle directory expand/collapse
left / right	Collapse / expand directory
d	Sort by date
n	Sort by name
s	Filter by source
esc	Back
q / ctrl+c	Quit

Session Picker:

Key	Action
enter	Select session
/	Search/filter
s	Filter by source
esc	Back to project picker
q / ctrl+c	Quit

Session Viewer:

Key	Action
up / down / j / k	Scroll
pgup / pgdn	Page up/down
g / G	Go to top / bottom
esc	Back to session picker
q / ctrl+c	Quit

Server Options

# Control HTTP logging
thinkt server --quiet              # Suppress HTTP logs
thinkt server --http-log file.log  # Log to file
thinkt server --no-open            # Don't auto-open browser

# Background management
thinkt server start                # Start in background
thinkt server status               # Check server status
thinkt server logs                 # View server logs
thinkt server logs -f              # Follow logs
thinkt server stop                 # Stop background server

Default Ports

Command	Port	Description
thinkt server	8784	Full web interface and REST API
thinkt web lite	8784	Lightweight debug webapp (served at /lite/)
thinkt server mcp --port	8786	MCP server over HTTP
VS Code extension	8787	Reserved for embedded server
thinkt collect	8785	Trace collector (includes /metrics)
thinkt-exporter --metrics-port	(disabled)	Exporter Prometheus metrics

Use -p or --port to override the default port for any server.

Authentication

Both the REST API server (thinkt server) and MCP server (thinkt server mcp) support Bearer token authentication to protect access to your conversation data.

Generate a Token

thinkt server token
# Output: thinkt_20260205_cd3bf36d6e1fc71e9bf033a7131f77cb

API Server Authentication

# Using environment variable
export THINKT_API_TOKEN=$(thinkt server token)
thinkt server

# Using command-line flag
thinkt server --token thinkt_20260205_...

# Client request
curl -H "Authorization: Bearer thinkt_20260205_..." http://localhost:8784/api/v1/sources

MCP Server Authentication

For stdio transport (default), authentication uses environment variables:

# Claude Desktop configuration with authentication
export THINKT_MCP_TOKEN=$(thinkt server token)

For HTTP transport:

# Using environment variable
export THINKT_MCP_TOKEN=$(thinkt server token)
thinkt server mcp --port 8786

# Using command-line flag
thinkt server mcp --port 8786 --token thinkt_20260205_...

Clients must pass the token in the Authorization header:

Authorization: Bearer thinkt_20260205_...

Cross-Platform Support

thinkt runs on macOS, Linux, and Windows. Platform-specific behavior is handled automatically:

• Default apps: Finder/Terminal/iTerm (macOS), xdg-open/x-terminal-emulator (Linux), Explorer/Windows Terminal/cmd (Windows), plus VS Code/Cursor/Zed on all platforms. Manage with thinkt apps
• Machine fingerprint: IOPlatformUUID (macOS), /etc/machine-id (Linux), registry MachineGuid (Windows)
• Browser opening: open (macOS), xdg-open (Linux), rundll32 (Windows)

Machine Fingerprint

Use thinkt server fingerprint to display a unique machine identifier. This fingerprint is derived from system identifiers (e.g., hardware UUID on macOS, /etc/machine-id on Linux, MachineGuid on Windows) and can be used to correlate sessions across different AI coding assistant sources on the same machine.

# Display fingerprint
thinkt server fingerprint

# JSON output
thinkt server fingerprint --json

The fingerprint is normalized to a consistent UUID format across all platforms.

Lite Webapp Features

For full trace exploration, use thinkt server which provides the full web interface on port 8784.

The lightweight webapp (thinkt web lite) provides a quick debug interface:

• Internationalization: English, Spanish, and Chinese (auto-detected)
• Connection Status: Real-time indicator showing server connectivity
• Source Visibility: Toggle eye icons to show/hide projects by source
• Open-In Buttons: Quick buttons to open projects in VS Code, Cursor, etc.
• Language Selector: Switch between EN/ES/中文 in the top-right corner

Trace Collector & Exporter

Aggregate traces from multiple machines with the push-based collector system.

Collector

# Start the collector server
thinkt collect                              # Default port 8785
thinkt collect --port 8785 --token mytoken  # With authentication

# Standalone binary
thinkt-collector --port 8785 --token mytoken

Collector data is stored in ~/.thinkt/collector.duckdb (separate from the indexer).

Exporter

# One-shot export of all traces
thinkt export

# Continuous watch mode
thinkt export --forward

# Export only Claude traces
thinkt export --source claude

# Flush the disk buffer
thinkt export --flush

# Standalone binary
thinkt-exporter --watch-dir ~/.claude/projects --collector-url http://collect.example.com/v1/traces

The exporter auto-discovers the collector via THINKT_COLLECTOR_URL env var, .thinkt/collector.json, or falls back to local buffering.

Prometheus Metrics

Both the collector and exporter expose Prometheus metrics for monitoring.

Collector — metrics are always available at /metrics on the collector port (no auth required):

curl -s http://localhost:8785/metrics | grep thinkt_

Exporter — opt-in via --metrics-port:

thinkt-exporter --collector-url http://localhost:8785/v1/traces --metrics-port 9090
curl -s http://localhost:9090/metrics | grep thinkt_

Metric	Type	Description
thinkt_collector_ingest_entries_total	counter	Entries ingested, by source
thinkt_collector_ingest_requests_total	counter	Ingest requests, by status
thinkt_collector_ingest_duration_seconds	histogram	Ingest request latency
thinkt_collector_active_agents	gauge	Currently active agents
thinkt_collector_db_size_bytes	gauge	DuckDB file size
thinkt_collector_ws_connections_active	gauge	Active WebSocket connections
thinkt_exporter_entries_shipped_total	counter	Entries shipped, by source
thinkt_exporter_entries_failed_total	counter	Entries that failed to ship
thinkt_exporter_ship_duration_seconds	histogram	Ship request latency
thinkt_exporter_buffer_size_bytes	gauge	Disk buffer size
thinkt_exporter_file_events_total	counter	File events processed

REST API

The thinkt server command provides a REST API for programmatic access:

# Start the server
thinkt server

# With authentication
export THINKT_API_TOKEN=$(thinkt server token)
thinkt server

API Endpoints

Endpoint	Description
GET /api/v1/sources	List available trace sources
GET /api/v1/projects	List all projects
GET /api/v1/projects/{id}/sessions	List sessions for a project
GET /api/v1/sessions/{path}	Get session content
GET /api/v1/info	Server info (fingerprint, version, uptime)
GET /api/v1/search?q=query	Search indexed sessions
GET /api/v1/semantic-search	Semantic search across sessions
GET /api/v1/stats	Get usage statistics
GET /api/v1/indexer/health	Check indexer health
GET /api/v1/indexer/status	Live indexer status
GET /api/v1/teams	List agent teams
POST /api/v1/open-in	Open path in application
GET /api/v1/open-in/apps	List allowed apps (with terminal info)
GET /api/v1/themes	List available themes

Swagger documentation is available at http://localhost:8784/swagger.

MCP Integration

Use thinkt as an MCP server for AI assistants like Claude Desktop:

{
  "mcpServers": {
    "thinkt": {
      "command": "thinkt",
      "args": ["server", "mcp"],
      "env": {
        "THINKT_MCP_TOKEN": "your-secure-token-here"
      }
    }
  }
}

Generate a secure token with:

thinkt server token

Available MCP tools:

• list_sources - List available session sources
• list_projects - List projects from all sources
• list_sessions - List sessions for a project
• get_session_metadata - Get session metadata
• get_session_entries - Get session content with pagination
• list_active_sessions - List currently active AI coding sessions
• search_sessions - Search across indexed sessions (supports regex)
• semantic_search - Search by meaning using on-device embeddings
• get_usage_stats - Get aggregate usage statistics

See Authentication for more details on securing the MCP server.

Data Directory (THINKT_HOME)

By default, thinkt stores its configuration, indexer databases, embeddings, instance registry, and other data in ~/.thinkt. Set the THINKT_HOME environment variable to override this location:

export THINKT_HOME=/path/to/custom/thinkt

Contents of THINKT_HOME:

Path	Purpose
config.json	User configuration (theme, language, apps)
instances.json	Running server instance registry
dbs/indexer.duckdb	DuckDB indexer database
embeddings/	Per-model embedding databases
machine_id	Fallback machine fingerprint

Environment Variables

Variable	Description	Default
THINKT_HOME	thinkt config and data directory	~/.thinkt
THINKT_CLAUDE_HOME	Claude Code data directory	~/.claude
THINKT_KIMI_HOME	Kimi Code data directory	~/.kimi
THINKT_GEMINI_HOME	Gemini CLI data directory	~/.gemini
THINKT_COPILOT_HOME	Copilot data directory	~/.copilot
THINKT_CODEX_HOME	Codex CLI data directory	~/.codex
THINKT_QWEN_HOME	Qwen Code data directory	~/.qwen
THINKT_LANG	Override UI language (BCP 47 tag)	auto-detected
THINKT_LOG_FILE	Write debug logs to this file path	(disabled)
THINKT_API_TOKEN	Bearer token for API server authentication	(none)
THINKT_MCP_TOKEN	Bearer token for MCP server authentication	(none)
THINKT_MCP_ALLOW_TOOLS	Comma-separated list of allowed MCP tools	(all)
THINKT_MCP_DENY_TOOLS	Comma-separated list of denied MCP tools	(none)
THINKT_CORS_ORIGIN	CORS Access-Control-Allow-Origin header	* (unauthenticated)
THINKT_COLLECTOR_URL	Collector endpoint URL for exporter	(auto-discover)
THINKT_API_KEY	Bearer token for collector authentication	(none)
THINKT_PROFILE	Write CPU profiling to this file path	(disabled)

Related Projects

• Thinking Tracer - visualization tool for exploring LLM conversation traces

License

Created with ❤ and 🔥 by the team at Neomantra and BrainSTM.

Released under the MIT License - see LICENSE.txt