name: obelisk-installer description: Install the official Obelisk CLI and then install the Obelisk agent skill. Use only for initial setup or repair when the obelisk command is missing. allowed-tools:

• Bash

Install Obelisk

This is a one-time bootstrap guide. It installs the local Obelisk runtime, then uses that runtime to install the official agent skill from github.com/tommy0103/obelisk-skill.

1. Check for the CLI

command -v obelisk >/dev/null 2>&1 && obelisk --version

If this succeeds, skip to step 3. Do not reinstall a working CLI unless the user asked to upgrade or repair it.

2. Install the CLI

Installing a global command changes the user's machine. Show the command and get the user's approval before running one of these official installation methods.

With npm:

npm install --global @obelisk-apps/cli

On macOS, Linux, or WSL, the official installer performs the same CLI-only installation and never installs an agent skill:

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

Never use sudo, install a daemon, or download Obelisk from another source.

Verify the result:

obelisk --version

3. Choose the skill installation scope

The standard skills installer defaults to the current project. Before running it, tell the user about that default and ask whether /obelisk should be installed:

• For the current project only — available only in the project where the installer runs.
• Globally — available across the user's projects.

Do not silently choose the current-project default. If the user already stated the scope explicitly, use that choice without asking again.

Run the command that matches the user's answer:

Current project:

obelisk install

Global:

obelisk install --global

Pass through any additional target options the user requested. The command uses the standard skills installer, so follow its prompts instead of copying skill files by hand.

After installation, tell the user to reload their agent if the new /obelisk skill is not discovered immediately. This bootstrap document is not the query skill and must not answer session-history questions itself.

Past Claude Code, Codex, and Kimi Code sessions -- queryable by your agent, browsable by you.

Two sides of the same index

Obelisk has two sides that share one SQLite index:

Agent side — the obelisk CLI owns the local runtime, while a separate agent skill teaches coding agents how to search and query their session history. The agent writes JS queries, runs them locally, and answers in plain language.

App side — an Electron desktop app for humans to browse sessions, manage memories, view usage stats, and see weekly recap cards.

Both read from the same ~/.obelisk/obelisk.sqlite database. The indexer reads Claude Code transcripts from ~/.claude/projects, Codex transcripts from ~/.codex/sessions, and Kimi Code sessions from ~/.kimi-code/sessions (or $KIMI_CODE_HOME/sessions).

Multi-provider support

Obelisk indexes every provider into the same SQLite schema instead of keeping separate databases. Rows carry a source value, and non-Claude IDs are provider-prefixed so they cannot collide.

Codex root threads become normal Obelisk sessions. Codex child threads are attached through the same subagents table when parent-thread metadata is available. Codex does not emit Claude-style workflow metadata, so workflow tables may be empty for Codex-only history.

Kimi session directories become one Obelisk session each. Main and child-agent wire.jsonl streams are projected into the same messages, tools, summaries and subagents tables. Undo/clear is handled as a full session replay, so retracted wire records do not remain in the index.

For live app refresh, Obelisk watches the roots declared by every registered provider, including ~/.claude/projects, ~/.codex/sessions, and ~/.kimi-code/sessions. Codex's session_index.jsonl is used as lightweight title/update metadata during indexing, not as the message transcript source.

Skill: agent-first retrieval

You can use obelisk like:

/obelisk 上次 auth bug 最后到底改了哪些文件，为什么这么改
/obelisk 这个文件最近在哪些 sessions 里被反复修改
/obelisk 找出最近失败的 tool calls，它们分别发生在哪些任务里
/obelisk 那个 review workflow 的 subagents 各自结论是什么
/obelisk recap this week

Install

Let your agent install it (recommended)

The shortest path is to give the bootstrap guide directly to a coding agent with shell access. Paste this as a prompt into Claude Code, Codex, or another agent — not into your terminal:

Install Obelisk by fetching and following this guide:
curl -fsSL https://raw.githubusercontent.com/tommy0103/obelisk/main/SKILL.md

The agent will ask before changing your machine, install and verify the CLI, then ask whether the formal /obelisk skill should be installed for the current project or globally. The bootstrap guide is only for one-time setup; it is not the query skill itself.

Install manually

Obelisk requires Node.js 22.13 or newer. Install the platform-neutral CLI:

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

On macOS, Linux, or WSL, the CLI-only installer is equivalent:

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

Then install the agent skill:

obelisk install

obelisk install delegates to the standard skills installer for tommy0103/obelisk-skill.

Then in any Claude Code session:

/obelisk <your question>

First run builds the index (~5 seconds for 100 sessions). After that it rebuilds incrementally.

How it works

You ask a question
  ↓
Agent writes a JS query against the SQLite index
  ↓
Runs it via obelisk --query <script>
  ↓
Reads the JSON result, answers in natural language

Core API: search(), context(), sql(), plus structured helpers (sessions, memories, summaries, workflows, failures, fileHistory, etc).

Memory layer

When a retrieval produces a conclusion worth keeping, the agent proposes a markdown memory file. After user approval, it registers the file with obelisk --attune <script>. Memories are recalled via memories() in future sessions — a synthesis cache, not a replacement for raw evidence.

App: A surface for humans

A companion desktop app for browsing the same index maintained by the CLI or the app daemon.

• Sessions — browse all sessions with search, project filtering, readable tool calls (diffs, terminal output, file viewers)
• Memory — list and detail views for registered memory files
• Activity — GitHub-style heatmap, weekly/cumulative token charts
• Recap — shareable weekly/monthly recap cards with archetype theming
• Settings — data source configuration, auto-refresh, rebuild index

Prebuilt releases are currently available for macOS from Releases. The source app can be run locally on macOS, Windows, and Linux.

Run locally

Install Node.js 22 and npm, then run the app from its own package directory:

git clone https://github.com/tommy0103/obelisk.git
cd obelisk/app
npm ci
npm run dev

electron-vite starts the renderer dev server and launches Electron. On first run, Obelisk creates ~/.obelisk/obelisk.sqlite, indexes the available Claude Code and Codex transcripts, and then watches them for changes. The default sources are ~/.claude/projects and ~/.codex/sessions; use Settings to point the app at different directories. On Windows, Obelisk also checks common WSL distributions for the Claude Code directory.

Debug the app

• Renderer changes use Vite hot module replacement. Open Electron DevTools with Cmd+Option+I on macOS or Ctrl+Shift+I on Windows/Linux.
• Main-process and preload logs appear in the terminal running npm run dev; their source changes are rebuilt by electron-vite.
• To attach a Node debugger to the Electron main process, start it with npm run dev -- --inspect=5858, then attach your debugger to port 5858.
• The development app reads and updates the real ~/.obelisk index. Back it up before testing destructive rebuilds. For an isolated run, launch with a disposable home directory (HOME=/tmp/obelisk-dev npm run dev on macOS/Linux, or set a temporary USERPROFILE first on Windows), then select fixture source directories in Settings.

better-sqlite3 provides prebuilt binaries for common platforms. If npm ci falls back to compiling it locally, install the platform's C/C++ build tools and run npm ci again.

What gets indexed

Full-text search via FTS5 covers all layers.

Structure

packages/core/                # @obelisk/core npm workspace (TypeScript + ESM)
├── src/
│   ├── providers/
│   │   ├── types.ts          # Provider + TranscriptRecord contract
│   │   ├── claude.ts         # Claude Code adapter (line-incremental)
│   │   ├── codex.ts          # Codex adapter (full-reparse)
│   │   └── kimi.ts           # Kimi Code adapter (session projection)
│   ├── session-detail.ts     # Provider-independent transcript projection
│   ├── persist.ts            # Binding-agnostic record writer (upsert/merge)
│   ├── tx.ts                 # Write transaction + connection config
│   ├── write-coordinator.ts  # Bounded retry policy
│   ├── writer-lease.ts       # Cross-process single-writer lease (SQLite lock DB)
│   ├── core.ts               # buildIndex / searchText / executeQuery / executeAttune
│   ├── indexer.ts            # Skill orchestration (discover → persist → finalize)
│   ├── parsing.ts            # Pure helpers (node:sqlite-free, app-consumable)
│   ├── db.ts                 # node:sqlite lifecycle + migrations
│   ├── query.ts              # Query/attune sandbox API (helpers)
│   └── schema.sql            # SQLite schema (single source of truth)
├── package.json
└── dist/                     # Generated package JS, declarations, and schema

packages/cli/                 # @obelisk-apps/cli npm workspace
├── src/obelisk.ts            # CLI shell + skill installer delegation
├── scripts/build.mjs         # Compiles CLI + readable Core into one package
├── package.json
└── dist/                     # Generated platform-neutral npm payload

skill-doc/                    # Source for the docs-only obelisk agent skill
├── SKILL.md                  # Query and memory workflow
└── references/               # Progressive-disclosure API/schema/pattern docs
    └── recap/                # Per-card recap retrieval + writing references

app/