clicodelog 0.2.2

---

Installation

Via uv tool (Recommended)

uv is a fast Python package installer. Install it first if you haven't:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then install clicodelog as an isolated tool:

uv tool install clicodelog

To upgrade:

uv tool upgrade clicodelog

Via pip

pip install clicodelog

From source

git clone https://github.com/monk1337/clicodelog.git
cd clicodelog
uv tool install -e .
# or with pip:
pip install -e .

---

Usage

After installation, simply run:

clicodelog

The app will:

• Auto-kill any process on port 6126 (if occupied)
• Sync data from all AI coding agent sources
• Start a web server at http://localhost:6126

Command Options

clicodelog --help               # Show all options
clicodelog --port 8080          # Use custom port
clicodelog --host 0.0.0.0       # Bind to all interfaces
clicodelog --no-sync            # Skip initial data sync
clicodelog --debug              # Run in debug mode

Alternative: Run from source

git clone https://github.com/monk1337/clicodelog.git
cd clicodelog
python -m clicodelog.cli

Features

• Multi-source support — View logs from Claude Code, OpenAI Codex, and Gemini CLI
• Three-panel layout — Projects → Sessions → Conversation
• Auto-sync — Backs up data from source directories every hour
• Export — Download any session as a .txt file
• Theme support — Light (soft blue) and Dark modes
• Rich display — User/assistant messages, thinking blocks, tool usage, token stats
• Search — Quickly find projects and sessions

---

Supported Tools

Tool	Source Directory	Status
Claude Code	~/.claude/projects/	✅ Supported
OpenAI Codex	~/.codex/sessions/	✅ Supported
Gemini CLI	~/.gemini/tmp/	✅ Supported

Claude Code

• Sessions organized by project directory
• Displays summaries, messages, thinking blocks, and tool usage
• Shows model metadata and token usage

OpenAI Codex

• Sessions organized by date (YYYY/MM/DD/)
• Groups sessions by working directory (cwd) as projects
• Displays messages, function calls, and reasoning blocks
• Filters out system prompts for cleaner inspection

Gemini CLI

• Sessions stored as JSON files in {hash}/chats/session-*.json
• Groups sessions by project hash
• Displays messages, thoughts (thinking), and tool calls
• Shows token usage (input, output, cached)

---

CLI Options

clicodelog --help               # Show help message
clicodelog --version            # Show version
clicodelog --port 8080          # Run on custom port (default: 6126)
clicodelog --host 0.0.0.0       # Bind to all interfaces (default: 127.0.0.1)
clicodelog --no-sync            # Skip initial data sync
clicodelog --debug              # Run in debug mode

Note: The app automatically kills any process running on the specified port before starting.

---

How It Works

• Startup sync — Copies logs from source directories into local ./data/
• Background sync — Automatically refreshes every hour
• Manual sync — Trigger a sync for the active source via UI
• Source switching — Switch between Claude Code, Codex, and Gemini CLI

---

Data Storage

data/
├── claude-code/          # Claude Code backup
│   ├── -Users-project1/
│   │   ├── session1.jsonl
│   │   └── session2.jsonl
│   └── -Users-project2/
├── codex/                # OpenAI Codex backup
│   └── 2026/
│       └── 01/
│           ├── 16/
│           │   └── rollout-xxx.jsonl
│           └── 17/
└── gemini/               # Gemini CLI backup
    ├── {project-hash-1}/
    │   └── chats/
    │       ├── session-2026-01-17T12-57-xxx.json
    │       └── session-2026-01-17T13-04-xxx.json
    └── {project-hash-2}/

---

Controls

Control	Action
Source dropdown	Switch between supported tools
📥 Export	Download current session as .txt
🔄 Sync	Manually refresh logs from source
☀️ / 🌙 Theme	Toggle light/dark mode

---

Screenshots

Light Mode	Dark Mode

---

Project Structure

clicodelog/
├── app.py              # Flask backend (multi-source support)
├── run.sh              # Run script
├── requirements.txt    # Dependencies
├── data/               # Synced logs (auto-created)
│   ├── claude-code/
│   ├── codex/
│   └── gemini/
└── templates/
    └── index.html      # Frontend

---

API Endpoints

Endpoint	Method	Description
/api/sources	GET	List available sources
/api/sources/<id>	POST	Set active source
/api/projects?source=	GET	List projects
/api/projects/<id>/sessions?source=	GET	List sessions
/api/projects/<id>/sessions/<id>?source=	GET	Fetch session
/api/sync?source=	POST	Trigger sync
/api/status?source=	GET	Sync status

---

Requirements

• Python 3.7+
• Flask 2.0+
• flask-cors

---

Adding New Sources

To add support for another CLI-based AI tool, update app.py:

SOURCES = {
    "claude-code": {
        "name": "Claude Code",
        "source_dir": Path.home() / ".claude" / "projects",
        "data_subdir": "claude-code"
    },
    "codex": {
        "name": "OpenAI Codex",
        "source_dir": Path.home() / ".codex" / "sessions",
        "data_subdir": "codex"
    },
    "gemini": {
        "name": "Gemini CLI",
        "source_dir": Path.home() / ".gemini" / "tmp",
        "data_subdir": "gemini"
    },
    # Add new tool here
}

Then implement the corresponding parser for its log format.

---

License

MIT

---