{"id":46503252,"url":"https://github.com/tensakulabs/chronicle","last_synced_at":"2026-03-09T17:07:18.071Z","repository":{"id":341846317,"uuid":"1171588151","full_name":"tensakulabs/chronicle","owner":"tensakulabs","description":null,"archived":false,"fork":false,"pushed_at":"2026-03-06T13:04:53.000Z","size":720,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-06T16:35:07.892Z","etag":null,"topics":["ai-agents","claude-code","code-indexing","code-search","context-window","cursor","developer-tools","mcp","mcp-server","sqlite","tree-sitter"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@tensakulabs/chronicle","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/tensakulabs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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-03-03T11:52:14.000Z","updated_at":"2026-03-06T16:27:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"5a400c1d-fe32-456d-a471-e49537c7a8e9","html_url":"https://github.com/tensakulabs/chronicle","commit_stats":null,"previous_names":["tensakulabs/chronicle"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/tensakulabs/chronicle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tensakulabs%2Fchronicle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tensakulabs%2Fchronicle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tensakulabs%2Fchronicle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tensakulabs%2Fchronicle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tensakulabs","download_url":"https://codeload.github.com/tensakulabs/chronicle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tensakulabs%2Fchronicle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30219234,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T14:02:48.375Z","status":"ssl_error","status_checked_at":"2026-03-07T14:02:43.192Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-agents","claude-code","code-indexing","code-search","context-window","cursor","developer-tools","mcp","mcp-server","sqlite","tree-sitter"],"created_at":"2026-03-06T14:13:57.136Z","updated_at":"2026-03-07T15:00:49.330Z","avatar_url":"https://github.com/tensakulabs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chronicle\n\n[![npm version](https://img.shields.io/npm/v/@tensakulabs/chronicle.svg)](https://www.npmjs.com/package/@tensakulabs/chronicle)\n[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Node.js 18+](https://img.shields.io/badge/Node.js-18%2B-brightgreen.svg)](https://nodejs.org/)\n[![MCP Server](https://img.shields.io/badge/MCP-Server-blue.svg)](https://modelcontextprotocol.io/)\n\n**Stop wasting 80% of your AI's context window on code searches.**\n\nChronicle is an MCP server that gives AI coding assistants instant access to your entire codebase through a persistent, pre-built index. Works with any MCP-compatible AI assistant: Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code Copilot, and more.\n\n![Chronicle Demo](docs/chronicle-demo.png)\n\n## The Problem\n\nEvery time your AI assistant searches for code, it:\n- **Greps** through thousands of files → hundreds of results flood the context\n- **Reads** file after file to understand the structure → more context consumed\n- **Forgets** everything when the session ends → repeat from scratch\n\nA single \"Where is X defined?\" question can eat 2,000+ tokens. Do that 10 times and you've burned half your context on navigation alone.\n\n## The Solution\n\nIndex once, query forever:\n\n```\n# Before: grep flooding your context\nAI: grep \"PlayerHealth\" → 200 hits in 40 files\nAI: read File1.cs, File2.cs, File3.cs...\n→ 2000+ tokens consumed, 5+ tool calls\n\n# After: precise results, minimal context\nAI: chronicle_query({ term: \"PlayerHealth\" })\n→ Engine.cs:45, Player.cs:23, UI.cs:156\n→ ~50 tokens, 1 tool call\n```\n\n**Result: 50-80% less context used for code navigation.**\n\n## Why Not Just Grep?\n\n| | Grep/Ripgrep | Chronicle |\n|---|---|---|\n| **Context usage** | 2000+ tokens per search | ~50 tokens |\n| **Results** | All text matches | Only identifiers |\n| **Precision** | `log` matches `catalog`, `logarithm` | `log` finds only `log` |\n| **Persistence** | Starts fresh every time | Index survives sessions |\n| **Structure** | Flat text search | Knows methods, classes, types |\n\n**The real cost of grep**: Every grep result includes surrounding context. Search for `User` in a large project and you'll get hundreds of hits — comments, strings, partial matches. Your AI reads through all of them, burning context tokens on noise.\n\n**Chronicle indexes identifiers**: It uses Tree-sitter to actually parse your code. When you search for `User`, you get the class definition, the method parameters, the variable declarations — not every comment that mentions \"user\".\n\n## How It Works\n\n1. **Index your project once** (~1 second per 1000 files)\n   ```\n   chronicle_init({ path: \"/path/to/project\" })\n   ```\n\n2. **AI searches the index instead of grepping**\n   ```\n   chronicle_query({ term: \"Calculate\", mode: \"starts_with\" })\n   → All functions starting with \"Calculate\" + exact line numbers\n\n   chronicle_query({ term: \"Player\", modified_since: \"2h\" })\n   → Only matches changed in the last 2 hours\n   ```\n\n3. **Get file overviews without reading entire files**\n   ```\n   chronicle_signature({ file: \"src/Engine.cs\" })\n   → All classes, methods, and their signatures\n   ```\n\nThe index lives in `.chronicle/index.db` (SQLite) — fast, portable, no external dependencies.\n\n## Features\n\n- **Screenshots**: Cross-platform screenshot capture (fullscreen, window, region) with auto-path for instant AI viewing\n- **Smart Extraction**: Uses Tree-sitter to parse code properly — indexes identifiers, not keywords\n- **Method Signatures**: Get function prototypes without reading implementations\n- **Project Summary**: Auto-detected entry points, main classes, language breakdown\n- **Incremental Updates**: Re-index single files after changes\n- **Cross-Project Links**: Query across multiple related projects\n- **Time-based Filtering**: Find what changed in the last hour, day, or week\n- **Project Structure**: Query all files (code, config, docs, assets) without filesystem access\n- **Session Notes**: Leave reminders for the next session — persists in the database\n- **Task Backlog**: Built-in task management that lives with your code index — no external tools needed\n- **Auto-Cleanup**: Excluded files (e.g., build outputs) are automatically removed from index\n\n## Supported Languages\n\n| Language | Extensions |\n|----------|------------|\n| C# | `.cs` |\n| TypeScript | `.ts`, `.tsx` |\n| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` |\n| Rust | `.rs` |\n| Python | `.py`, `.pyw` |\n| C | `.c`, `.h` |\n| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx` |\n| Java | `.java` |\n| Go | `.go` |\n| PHP | `.php` |\n| Ruby | `.rb`, `.rake` |\n\n## Quick Start\n\n### 1. Install \u0026 Register\n\n```bash\nnpm install -g @tensakulabs/chronicle\nchronicle setup\n```\n\n`chronicle setup` automatically detects and registers Chronicle with your installed AI clients (Claude Code, Claude Desktop, Cursor, Windsurf, Gemini CLI, VS Code Copilot). To unregister: `chronicle unsetup`.\n\n### 2. Or register manually with your AI assistant\n\n**For Claude Code** (`~/.claude/settings.json` or `~/.claude.json`):\n```json\n{\n  \"mcpServers\": {\n    \"chronicle\": {\n      \"type\": \"stdio\",\n      \"command\": \"chronicle\",\n      \"env\": {}\n    }\n  }\n}\n```\n\n**For Claude Desktop** (`%APPDATA%/Claude/claude_desktop_config.json` on Windows):\n```json\n{\n  \"mcpServers\": {\n    \"chronicle\": {\n      \"command\": \"chronicle\"\n    }\n  }\n}\n```\n\n\u003e **Note:** The server name in your config determines the MCP tool prefix. Use `\"chronicle\"` as shown above — this gives you tool names like `chronicle_query`, `chronicle_signature`, etc.\n\n**For Gemini CLI** (`~/.gemini/settings.json`):\n```json\n{\n  \"mcpServers\": {\n    \"chronicle\": {\n      \"command\": \"chronicle\"\n    }\n  }\n}\n```\n\n**For VS Code Copilot** (run `MCP: Open User Configuration` in Command Palette):\n```json\n{\n  \"servers\": {\n    \"chronicle\": {\n      \"type\": \"stdio\",\n      \"command\": \"chronicle\"\n    }\n  }\n}\n```\n\n### 3. Make your AI actually use it\n\nAdd to your AI's instructions (e.g., `~/.claude/CLAUDE.md` for Claude Code):\n\n```markdown\n## Chronicle — Use for ALL code searches!\n\n**Before using Grep/Glob, check if `.chronicle/` exists in the project.**\n\nIf yes, use Chronicle instead:\n- `chronicle_query` — Find functions, classes, variables by name\n- `chronicle_signature` — Get all methods in a file with line numbers\n- `chronicle_signatures` — Get methods from multiple files (glob pattern)\n- `chronicle_summary` — Project overview with entry points\n\nIf no `.chronicle/` exists, offer to run `chronicle_init` first.\n```\n\n### 4. Index your project\n\nAsk your AI: *\"Index this project with Chronicle\"*\n\nOr manually in the AI chat:\n```\nchronicle_init({ path: \"/path/to/your/project\" })\n```\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `chronicle_init` | Index a project (creates `.chronicle/`) |\n| `chronicle_query` | Search by term (exact/contains/starts_with) |\n| `chronicle_signature` | Get one file's classes + methods |\n| `chronicle_signatures` | Get signatures for multiple files (glob) |\n| `chronicle_update` | Re-index a single changed file |\n| `chronicle_remove` | Remove a deleted file from index |\n| `chronicle_summary` | Project overview |\n| `chronicle_tree` | File tree with statistics |\n| `chronicle_describe` | Add documentation to summary |\n| `chronicle_link` | Link another indexed project |\n| `chronicle_unlink` | Remove linked project |\n| `chronicle_links` | List linked projects |\n| `chronicle_status` | Index statistics |\n| `chronicle_scan` | Find indexed projects in directory tree |\n| `chronicle_files` | List project files by type (code/config/doc/asset) |\n| `chronicle_note` | Read/write session notes (persists between sessions) |\n| `chronicle_session` | Start session, detect external changes, auto-reindex |\n| `chronicle_viewer` | Open interactive project tree in browser |\n| `chronicle_task` | Create, read, update, delete tasks with priority and tags |\n| `chronicle_tasks` | List and filter tasks by status, priority, or tag |\n| `chronicle_screenshot` | Take a screenshot (fullscreen, window, region) |\n| `chronicle_windows` | List open windows for screenshot targeting |\n\n## Time-based Filtering\n\nTrack what changed recently with `modified_since` and `modified_before`:\n\n```\nchronicle_query({ term: \"render\", modified_since: \"2h\" })   # Last 2 hours\nchronicle_query({ term: \"User\", modified_since: \"1d\" })     # Last day\nchronicle_query({ term: \"API\", modified_since: \"1w\" })      # Last week\n```\n\nSupported formats:\n- **Relative**: `30m` (minutes), `2h` (hours), `1d` (days), `1w` (weeks)\n- **ISO date**: `2026-01-27` or `2026-01-27T14:30:00`\n\n## Project Structure Queries\n\nChronicle indexes ALL files in your project (not just code):\n\n```\nchronicle_files({ path: \".\", type: \"config\" })  # All config files\nchronicle_files({ path: \".\", type: \"test\" })    # All test files\nchronicle_files({ path: \".\", pattern: \"**/*.md\" })  # All markdown files\nchronicle_files({ path: \".\", modified_since: \"30m\" })  # Changed this session\n```\n\nFile types: `code`, `config`, `doc`, `asset`, `test`, `other`, `dir`\n\n## Session Notes\n\nLeave reminders for the next session:\n\n```\nchronicle_note({ path: \".\", note: \"Test the glob fix after restart\" })  # Write\nchronicle_note({ path: \".\", note: \"Also check edge cases\", append: true })  # Append\nchronicle_note({ path: \".\" })                                              # Read\nchronicle_note({ path: \".\", clear: true })                                 # Clear\n```\n\nNotes are stored in `.chronicle/index.db` and persist indefinitely.\n\n## Task Backlog\n\nKeep your project tasks right next to your code index:\n\n```\nchronicle_task({ path: \".\", action: \"create\", title: \"Fix parser bug\", priority: 1, tags: \"bug\" })\nchronicle_task({ path: \".\", action: \"update\", id: 1, status: \"done\" })\nchronicle_task({ path: \".\", action: \"log\", id: 1, note: \"Root cause: unbounded buffer\" })\nchronicle_tasks({ path: \".\", status: \"active\" })\n```\n\n**Priorities**: 🔴 high, 🟡 medium, ⚪ low  \n**Statuses**: `backlog → active → done | cancelled`\n\n## Screenshots\n\n```\nchronicle_screenshot()                                              # Full screen\nchronicle_screenshot({ mode: \"active_window\" })                     # Active window\nchronicle_screenshot({ mode: \"window\", window_title: \"VS Code\" })   # Specific window\nchronicle_windows({ filter: \"chrome\" })                             # Find window titles\n```\n\nCross-platform: Windows (PowerShell), macOS (screencapture), Linux (maim/scrot).\n\n## Interactive Viewer\n\n```\nchronicle_viewer({ path: \".\" })\n```\n\nOpens `http://localhost:3333` with an interactive file tree, file signatures, live reload, and git status icons.\n\nClose with `chronicle_viewer({ path: \".\", action: \"close\" })`\n\n![Chronicle Viewer](docs/chronicle-viewer.png)\n\n![Chronicle Viewer Code](docs/chronicle-viewer-code.png)\n\n## CLI Usage\n\n```bash\nchronicle scan ~/projects       # Find all indexed projects\nchronicle init ./myproject      # Index a project from command line\n```\n\n## Performance\n\n| Project Size | Files | Items | Index Time | Query Time |\n|-------------|-------|-------|------------|------------|\n| Small | ~20 | 1,200 | \u003c1s | 1-5ms |\n| Medium | ~50 | 1,900 | \u003c1s | 1-5ms |\n| Large | ~100 | 3,000 | \u003c1s | 1-5ms |\n| XL | ~500 | 4,100 | ~2s | 1-10ms |\n\n## Technology\n\n- **Parser**: [Tree-sitter](https://tree-sitter.github.io/) — real parsing, not regex\n- **Database**: SQLite with WAL mode — fast, single file, zero config\n- **Protocol**: [MCP](https://modelcontextprotocol.io/) — works with any compatible AI\n\n## Project Structure\n\n```\n.chronicle/              ← Created in YOUR project\n├── index.db             ← SQLite database\n└── summary.md           ← Optional documentation\n\nchronicle/               ← This repository\n├── src/\n│   ├── commands/        ← Tool implementations\n│   ├── db/              ← SQLite wrapper\n│   ├── parser/          ← Tree-sitter integration\n│   └── server/          ← MCP protocol handler\n└── build/               ← Compiled output\n```\n\n## Contributing\n\nPRs welcome.\n\n## License\n\nMIT © 2026 Tensaku Labs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftensakulabs%2Fchronicle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftensakulabs%2Fchronicle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftensakulabs%2Fchronicle/lists"}