{"id":51234671,"url":"https://github.com/catesandrew/agents-session-viewer","last_synced_at":"2026-06-28T19:03:04.191Z","repository":{"id":356999240,"uuid":"1234897292","full_name":"catesandrew/agents-session-viewer","owner":"catesandrew","description":"Desktop app for browsing, searching, and exporting AI coding session histories","archived":false,"fork":false,"pushed_at":"2026-05-10T20:25:26.000Z","size":3842,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-10T22:18:32.765Z","etag":null,"topics":["ai","codex","desktop-app","developer-tools","electron","macos","nextjs","session-viewer","typescript"],"latest_commit_sha":null,"homepage":"https://catesandrew.github.io/agents-session-viewer/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/catesandrew.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-10T19:30:11.000Z","updated_at":"2026-05-10T20:24:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/catesandrew/agents-session-viewer","commit_stats":null,"previous_names":["catesandrew/agents-session-viewer"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/catesandrew/agents-session-viewer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catesandrew%2Fagents-session-viewer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catesandrew%2Fagents-session-viewer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catesandrew%2Fagents-session-viewer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catesandrew%2Fagents-session-viewer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/catesandrew","download_url":"https://codeload.github.com/catesandrew/agents-session-viewer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catesandrew%2Fagents-session-viewer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34900368,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","codex","desktop-app","developer-tools","electron","macos","nextjs","session-viewer","typescript"],"created_at":"2026-06-28T19:03:03.438Z","updated_at":"2026-06-28T19:03:04.184Z","avatar_url":"https://github.com/catesandrew.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agents Session Viewer\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![Electron](https://img.shields.io/badge/Electron-39.x-47848F?logo=electron\u0026logoColor=white)](https://www.electronjs.org/)\n\nA desktop application for browsing, searching, and exporting AI coding session histories. Built with Electron and Next.js, it reads Codex CLI JSONL log files and presents them in a clean, navigable interface with Vim-style keyboard shortcuts.\n\n**[Documentation](https://catesandrew.github.io/agents-session-viewer/)**\n\n## Screenshots\n\n\u003e Screenshots coming soon.\n\n## Features\n\n- **Auto-Discovery** -- Automatically scans `~/.codex/sessions/` and discovers all JSONL session files organized by date. New sessions appear in real-time via file watching.\n- **Fuzzy Search** -- Search across all sessions simultaneously with Fuse.js-powered fuzzy matching. Results highlight matched messages with context and allow jumping directly to the source.\n- **Vim-Style Navigation** -- Full keyboard-driven workflow: `j`/`k` for messages, `J`/`K` for sessions, `gg`/`G` for jumping, `y` to yank, `o` to collapse, and `/` to search.\n- **Rich Markdown Rendering** -- Syntax-highlighted code blocks (180+ languages), GFM tables, task lists, emoji, blockquotes, and more via react-markdown with remark/rehype plugins.\n- **macOS Native Integration** -- Share sheet support, native save dialogs for Markdown/JSON export, and proper window management with `Cmd` shortcuts.\n- **Light \u0026 Dark Themes** -- Follows system preference with manual override. Persists across sessions via localStorage.\n- **Session Grouping** -- Multiple JSONL files sharing a `sessionId` are unified into a single conversation view.\n- **Smart Titles** -- Sessions are titled using the first user message, working directory, or filename as fallback.\n- **Export Options** -- Save conversations as Markdown or JSON files, copy to clipboard, or share via macOS share sheet.\n\n## Installation\n\n### Pre-built binaries\n\nDownload a pre-built application for your platform from the [GitHub Releases](https://github.com/catesandrew/agents-session-viewer/releases) page. Available as macOS (.dmg), Linux (.AppImage), and Windows (.exe) installers.\n\n## Quick Start\n\n### Prerequisites\n\n- [Node.js](https://nodejs.org/) 20+\n- [pnpm](https://pnpm.io/) 9+\n\n### Install\n\n```bash\ngit clone https://github.com/catesandrew/agents-session-viewer.git\ncd agents-session-viewer\npnpm install\n```\n\n### Development\n\n```bash\n# Run Next.js dev server only (browser)\npnpm dev\n\n# Run full Electron app in dev mode\npnpm electron:dev\n```\n\n### Build\n\n```bash\n# Build Next.js static export\npnpm build\n\n# Build distributable Electron app\npnpm electron:build\n```\n\nThe packaged app will be in the `dist/` directory.\n\n## Keyboard Shortcuts\n\n### Navigation\n\n| Key | Action |\n|-----|--------|\n| `j` / `k` | Next / previous message |\n| `J` / `K` | Next / previous session |\n| `gg` | Jump to first message |\n| `G` | Jump to last message |\n| `Ctrl+d` / `Ctrl+u` | Scroll half page down / up |\n| `Space` | Page down |\n\n### Actions\n\n| Key | Action |\n|-----|--------|\n| `o` | Toggle collapse on selected message |\n| `y` | Copy selected message to clipboard |\n| `Y` | Copy entire conversation as Markdown |\n| `/` | Focus search input |\n| `Esc` | Clear search / unfocus |\n\n### macOS Shortcuts\n\n| Key | Action |\n|-----|--------|\n| `Cmd+S` | Save as Markdown |\n| `Cmd+Shift+S` | Save as JSON |\n| `Cmd+E` | Share via macOS share sheet |\n| `Cmd+B` | Toggle sidebar |\n\nSee the [full keyboard shortcuts reference](https://catesandrew.github.io/agents-session-viewer/docs/keyboard-shortcuts) for details.\n\n## File Format\n\nThe app reads Codex CLI session logs stored as JSONL (JSON Lines) files:\n\n```\n~/.codex/sessions/\n  └── YYYY/\n      └── MM/\n          └── DD/\n              └── rollout-YYYY-MM-DDTHH-MM-SS-GUID.jsonl\n```\n\nEach line in a `.jsonl` file is a standalone JSON object representing a session event:\n\n```json\n{\"type\":\"message\",\"role\":\"user\",\"content\":[{\"type\":\"input_text\",\"text\":\"...\"}],\"created_at\":1234567890}\n{\"type\":\"message\",\"role\":\"assistant\",\"content\":[{\"type\":\"output_text\",\"text\":\"...\"}],\"created_at\":1234567891}\n```\n\n## Architecture\n\nThe app follows an Electron two-process model:\n\n- **Main Process** (`electron/main.js`) -- Manages the BrowserWindow, file system access, JSONL parsing, file watching with chokidar, and IPC communication. Handles native menus, dialogs, and the macOS share sheet.\n- **Renderer Process** (Next.js app in `src/`) -- React-based UI with server components. Communicates with the main process via IPC for session data, search, and export operations.\n\n### Key Components\n\n| Directory | Purpose |\n|-----------|---------|\n| `electron/` | Main process entry point, IPC handlers, file watchers |\n| `src/app/` | Next.js app router pages and layouts |\n| `src/components/` | React UI components (session list, message view, search) |\n| `src/lib/` | Shared utilities, types, and helpers |\n| `public/` | Static assets |\n| `assets/` | App icons and platform-specific resources |\n\n## Tech Stack\n\n- **Runtime**: [Electron](https://www.electronjs.org/) 39.x\n- **Framework**: [Next.js](https://nextjs.org/) 16 (static export)\n- **Language**: [TypeScript](https://www.typescriptlang.org/) 5.x\n- **UI**: [React](https://react.dev/) 19, [Radix UI](https://www.radix-ui.com/), [Tailwind CSS](https://tailwindcss.com/) 4\n- **Search**: [Fuse.js](https://www.fusejs.io/) (fuzzy matching)\n- **Markdown**: [react-markdown](https://github.com/remarkjs/react-markdown) with remark-gfm, rehype-highlight\n- **File Watching**: [chokidar](https://github.com/paulmillr/chokidar)\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/my-feature`)\n3. Commit your changes (`git commit -m 'Add my feature'`)\n4. Push to the branch (`git push origin feature/my-feature`)\n5. Open a Pull Request\n\nPlease ensure your code passes linting (`pnpm lint`) before submitting.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatesandrew%2Fagents-session-viewer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcatesandrew%2Fagents-session-viewer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatesandrew%2Fagents-session-viewer/lists"}