Obelisk: A Local SQLite Index Over Claude Code, Codex, Kimi Code, Pi and DeepSeek Harness Session History

The problem: session transcripts that accumulate faster than anyone reads them

Coding agents write their history to disk in provider-specific formats. Claude Code transcripts live under ~/.claude/projects, Codex under ~/.codex/sessions and ~/.codex/archived_sessions, Kimi Code under ~/.kimi-code/sessions or $KIMI_CODE_HOME/sessions, Pi under ~/.pi/agent/sessions, and DeepSeek Harness under ~/.dsh/sessions or $DSH_HOME/sessions. Each format is a different shape of JSONL or directory tree. The practical result is that an answer to a question like which sessions touched a given file, or what a review workflow's subagents each concluded, requires remembering where the transcripts live and writing a parser for each one. Obelisk targets that gap. It reads all five roots, projects them into one schema, and lets the query be written once. The intended audience is a developer who already runs at least one of these agents daily and has accumulated history worth searching, plus the agent itself, which is given a skill so it can answer questions about its own past work.

One SQLite file, two consumers, and a provider-agnostic adapter layer

The architecture is a single database at ~/.obelisk/obelisk.sqlite that both the CLI and the Electron app read. The indexer walks each provider's transcript root and writes into shared tables: messages, tools, summaries, subagents, workflows, memories, and usage. Rows carry a source value, and non-Claude IDs are provider-prefixed so identifiers from different providers cannot collide. That is the central design decision, and it is what makes cross-provider queries possible at all. The alternative, one database per provider, would push the join back onto the caller.

The adapters differ in how much structure they can recover. Codex root threads become normal sessions, and Codex child threads attach through the same subagents table when parent-thread metadata is present. Codex does not emit Claude-style workflow metadata, so the README states plainly that workflow tables may be empty for Codex-only history. Kimi session directories become one Obelisk session each, with main and child-agent wire.jsonl streams projected into the same tables; undo and clear are handled as a full session replay so retracted records do not survive in the index. Pi is the most involved adapter: its tree, branch summaries, compactions, durable leaf, retained checkpoint tail, custom messages, bash records, tool calls, token usage and raw JSONL evidence all stay inside the adapter, with no Pi-specific database or renderer branch. Active visibility follows Pi's own context rules, where a retained tail replaces pre-compaction ancestors, and entries the source explicitly superseded are stored as inactive. The app and normal agent queries omit inactive rows; supported helpers can include them with includeInactive: true. Display-suppressed or transport-only records stay hidden and are never returned by those helpers.

The README's own comparison table is the honest part of the design. Pi attests branch, leaf and compaction state. Kimi Code can attest supersession through undo/clear but the README notes preservation is a follow-up. Claude Code, according to the table, does not attest rewind or current-leaf state. Codex has no branching semantics at all. So the index is only as faithful as the source: for two of the five providers, a query cannot tell you whether a message was later retracted.

The query path: the agent writes JavaScript, the CLI runs it

The retrieval model is not a search UI. The README describes the flow as: you ask a question, the agent writes a JS query against the SQLite index, runs it via obelisk --query <script>, reads the JSON result, and answers in natural language. The core API is search(), context() and sql(), plus structured helpers named sessions, memories, summaries, workflows and failures. Because the query language is JavaScript against a local database, the ceiling is whatever SQLite can express, not whatever a search box was designed to express. That is a real advantage for questions of the form find the failed tool calls and group them by task, and a real cost for anyone who wanted a fixed command surface.

The agent side depends on a separate skill repository, tommy0103/obelisk-skill, installed by obelisk install, which delegates to the standard skills installer. The README is explicit that the bootstrap guide in SKILL.md is for one-time setup and is not the query skill itself. In Claude Code the skill is invoked as /obelisk followed by a question in natural language. The README's own examples are in Chinese, covering questions like which files an auth bug fix touched and why, which sessions repeatedly modified a file, and which failed tool calls occurred in which tasks.

Install and first run

Obelisk requires Node.js 22.13 or newer. The platform-neutral CLI installs from npm:

npm install --global @obelisk-apps/cli obelisk --version

On macOS, Linux or WSL, the README treats the shell installer as equivalent:

curl -fsSL https://raw.githubusercontent.com/tommy0103/obelisk/main/install.sh | sh

Then obelisk install sets up the agent skill. The README's recommended path is to hand the bootstrap guide to a coding agent rather than running it yourself, by pasting the curl command for SKILL.md as a prompt into Claude Code, Codex or another agent. The README states the agent will ask before changing the machine, install and verify the CLI, then ask whether the formal skill should be installed for the current project or globally. First run builds the index, which the README puts at roughly 5 seconds for 100 sessions; subsequent runs are incremental.

For live refresh, the app watches the roots declared by every registered provider. Codex's session_index.jsonl is used as lightweight title and update metadata during indexing, not as the message transcript source. Pi's session directory is resolved in a fixed order: --session-dir, then PI_CODING_AGENT_SESSION_DIR, then sessionDir in settings, then the default under ~/.pi/agent/sessions. Obelisk follows absolute or ~-prefixed environment and global settings, plus the project setting for its own launch cwd, resolving a relative project setting against that cwd. The README names three cases it will not guess at: CLI-only roots, relative environment or global settings, and project settings from another launch cwd. In those cases you select the resolved directory in Settings.

Where the index is thinner than it looks

The superseded-history table is the limitation to read first. If your question is which files a Claude Code session ultimately changed, the source does not attest rewind or current-leaf state, so the index cannot distinguish a change that stuck from one that was reverted. The same class of question is unanswerable for Codex, which has no branching semantics. Pi is the only provider where this is handled thoroughly, and Kimi Code is partial by the README's own admission. A team that standardised on Claude Code and expects Obelisk to reconstruct the final state of a working tree is going to be disappointed.

The second constraint is provider coverage in the schema rather than in the file list. Workflow tables may be empty for Codex-only history, so any query joining sessions to workflows returns nothing for those users. Third, the query path assumes an agent that can write and run JavaScript. If you want a stable CLI verb for a recurring question, you are writing it yourself against the sql() helper. The README does not describe a query cache, saved queries, or a permission model for what the agent may execute, and those absences matter if you point the skill at a machine holding sensitive transcripts.

How it differs from a full-text search over transcript files

The obvious alternative is a text search tool such as ripgrep over the raw JSONL directories, or a general log-search stack that ingests the files and indexes them for full-text matching. The difference is in what the two approaches can answer. A grep over ~/.claude/projects finds the string auth in a transcript; it cannot tell you that this message belongs to a subagent of a particular workflow, that the session has since been superseded, or that the tool call failed. Obelisk's value is the projection into relational tables: sessions, messages, tools, subagents, summaries, workflows, failures, memories, usage. Questions that group, join or aggregate are natural against that schema and awkward against raw files.

The trade-off runs the other way too. A grep over files needs no indexer, no schema migration, and no adapter that can fall behind a provider's format change. Obelisk's fidelity is bounded by each adapter's understanding of the source format, and the README's superseded-history table is essentially a public statement of where that understanding stops. If your questions are lexical rather than structural, the index is overhead. If they are structural, the index is the point.

Licence, maintenance and what to verify before committing

Obelisk is AGPL-3.0. That matters if you plan to modify it and expose it as a network service, because the licence's network clause reaches users interacting with a modified version over a network. Reading the LICENSE file and, where the stakes are real, taking legal advice is the right move; nothing here substitutes for that. The repository is not archived, and the release history shows a steady cadence through mid-2026: v0.2.0 in July 2026 unified the Claude Code and Codex index, v0.2.1 added Kimi Code, and v0.2.2 in August 2026 added inline images, source links and cleaner session history. The README also flags at least one item as unfinished, noting that preserving Kimi supersession is a follow-up, so the schema is still moving.

The maintenance cost sits in the adapters. Each provider's transcript format can change independently, and the README documents format differences across Pi JSONL v1 through v3, so version drift is an ongoing concern rather than a one-time integration. Upgrading Obelisk means re-indexing or migrating ~/.obelisk/obelisk.sqlite, and the release notes are the place to check whether a schema change requires a rebuild. Before adopting, verify three things on your own machine: that node --version reports 22.13 or higher, that the provider roots you actually use exist at the documented paths, and that the questions you care about are answerable given the superseded-history limits for your provider. If your primary question is which files a Claude Code session changed in its final state, Obelisk will not answer it, and no amount of query writing will change that.

Editorial conclusion

Adopt Obelisk if you run more than one coding agent and want a single local index you can query with SQL or JavaScript instead of grepping JSONL by hand. Do not adopt it if you need guaranteed attribution of which files a session actually changed: the README says Claude Code does not attest rewind or current-leaf state, so superseded history is not recoverable there. Before installing, check that Node.js is at 22.13 or newer, confirm which provider roots exist on your machine, and read the AGPL-3.0 terms if you intend to redistribute anything built on the code.

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. tommy0103/obelisk on GitHub