Native on      

Codemark is a structural bookmarking system for code. Unlike fragile file:line references that break when you insert a single newline, Codemark uses tree-sitter to capture the semantic structure of what you marked — so bookmarks self-heal across renames, refactors, and reformatting.

That makes them durable enough for long-running AI agent sessions, code audits, and personal knowledge management.

🌐 Website & docs: danielcardonarojas.github.io/codemark

---

📑 Table of Contents

• Use It With Claude Code
• Native Dashboard (TUI)
• Features
• Installation
• Quick Start
• Supported Languages
• Customizing Markdown Output
• Documentation
• Built With
• License

---

⚡ Use It With Claude Code

Codemark is built for AI coding agents. One command teaches your agent to create and recall structural bookmarks, so context survives between sessions instead of being re-derived from scratch every time you open a chat.

codemark install-skill --agent claude --scope user

Then just ask, in any session:

"Trace how a request flows from the HTTP router to the database. Create a collection called request-lifecycle and bookmark each key hop — the route handler, the auth middleware, the service layer, and the query builder. Add a short note to each explaining its role."

Later — even after the code has been refactored, in a brand-new session — you (or another agent) reload that context instantly:

"Load the request-lifecycle collection and walk me through it."

Because the bookmarks are structural, they still resolve after the underlying code has moved or changed. Works with Claude Code, GitHub Copilot, Gemini CLI, and any agent that loads .agents/skills.

What you can ask for

Once a flow is captured as a collection, that knowledge becomes reusable — by you, your teammates, and future agent sessions:

• 🧭 Onboard a new engineer —

  "Load the request-lifecycle collection and give me a guided tour of how this service handles a request, in the order the code runs."

• 🔎 Explain a code flow —

  "Bookmark the steps of the checkout flow into a checkout collection, then summarize what each step is responsible for."

• 🐞 Hunt a bug in a known flow —

  "There's a bug where expired tokens are still accepted. Read the auth-flow collection and tell me which hop is most likely responsible."

• 🔗 Relate two flows —

  "Compare the request-lifecycle and background-jobs collections — where do they share code or state, and where could they conflict?"

📘 Walkthrough: Agent Workflow Guide · Agent Skill source

---

🖥️ Native Dashboard (TUI)

Codemark features a built-in, keyboard-driven dashboard inspired by lazygit. It's the primary interface for managing structural bookmarks, collections, and tours.

codemark tui

Requires a Nerd Font. The dashboard uses glyph icons throughout — set your terminal to a Nerd Font (e.g. JetBrainsMono Nerd Font) so they render correctly instead of showing as □ placeholders.

🎬 More demos

Settings overlay

FTS & semantic search

Filter pane contents

See the Demo Gallery for the full-size animated walkthroughs.

Themes

The TUI ships with built-in color schemes that re-theme the whole interface. Set one in your config (tui.theme) or via the CODEMARK_TUI_THEME environment variable; run codemark-tui --list-schemes to see what's available.

Catppuccin Mocha	Everforest Dark

Dashboard features

• ⌨️ Keyboard-driven, vim-style navigation — A lazygit-like, fully keyboard-first interface. Move with j/k (or arrows), cycle panes with Tab, switch tabs with [ / ], and resize panes with + / -. Press ? at any time for a context-aware help overlay.
• 🔄 Push / pull syncing — Publish collections and tours to a remote codetours server with P (push), and pull shared tours back down with p. Share curated walkthroughs across a team.
• 🔍 Semantic & full-text search — Press / to search, then toggle between FTS (SQLite full-text) and Semantic (local vector embeddings) modes. FTS finds exact terms; Semantic finds bookmarks by meaning — no API key required.
• 📝 Customizable markdown previews — The details and collection-overview panes render through Handlebars templates. Drop your own details_panel.md or codemark_collection_overview.md into the config directory to reshape what's shown.
• 🎨 Colorschemes & themes — Set [tui].theme in your config. Bundled options include OneHalfDark (default), Dracula, Nord, gruvbox-dark, Solarized, Catppuccin Mocha, and more. Base16/base24 schemes theme both the code preview and the surrounding UI chrome; drop your own .tmTheme or base16 .yaml files into the themes/ config subdirectory to add custom ones. See Configuration.
• ✏️ Open in any editor — Press o on a bookmark to jump straight to the code in your configured editor (terminal or GUI). Configure per–file-extension commands via the [open] config section — see Configuration.

---

🛠️ Features

• 🧠 Smart Resolution: Bookmarks survive renames and structural changes via tiered matching (Exact → Relaxed → Hash Fallback).
• 🖥️ Interactive Dashboard: Lazygit-style TUI for efficient, keyboard-first interaction.
• 📑 Rich Metadata: Captures AST structure, git context, content hashes, and append-only notes/tags.
• 🔍 Semantic Search: Find code by intent (e.g., "where is authentication handled?") with local embeddings — no API key.
• 🗃️ Collections: Group bookmarks into logical sets for specific tasks.
• 📦 Git Integrated: Track bookmarks across commits and branches.
• 🧩 Agent Skills: An installable skill that teaches AI coding agents to bookmark for you — works with Claude Code, GitHub Copilot, Gemini CLI, and any agent that loads .agents/skills.

---

💻 Installation

Prebuilt binaries are published for macOS (Apple Silicon & Intel), Linux (x86_64, glibc), and Windows (x86_64). Choose whichever method you prefer.

Homebrew (macOS / Linux)

brew install DanielCardonaRojas/codemark/codemark

Install script (macOS / Linux)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/DanielCardonaRojas/codemark/releases/latest/download/codemark-cli-installer.sh | sh

PowerShell (Windows)

powershell -ExecutionPolicy Bypass -c "irm https://github.com/DanielCardonaRojas/codemark/releases/latest/download/codemark-cli-installer.ps1 | iex"

mise

mise use -g github:DanielCardonaRojas/codemark

Cargo (build from source)

cargo install --git https://github.com/DanielCardonaRojas/codemark codemark-cli

Requires Rust 1.85+ (edition 2024). SQLite is bundled.

The script, PowerShell, and mise methods install prebuilt binaries from the GitHub releases. You can also download a platform archive there directly.

Terminal UI (optional)

codemark tui opens the interactive dashboard, a separate companion binary. Homebrew installs it automatically alongside the CLI. The other prebuilt methods (script, PowerShell, mise) install the codemark CLI only; add the dashboard with:

cargo install --git https://github.com/DanielCardonaRojas/codemark codemark-tui

---

🚦 Quick Start

Repo-aware by default. Codemark automatically detects the current Git repository (walking up from your working directory) and stores bookmarks alongside it — no setup required. You can also operate on a repo from any path by referencing it by identity with --repo <owner/name>, or point at a specific database with --db <path> / the CODEMARK_DB env var.

Prefer to drive it yourself instead of through an agent? The CLI is all you need.

1. Bookmark a range

codemark add --file src/auth.rs --range 42-67 --tag auth --note "token validation entrypoint"

2. Find it again — even after the code moves

codemark list                 # see everything you've marked
codemark resolve <id>         # re-locate a single bookmark
codemark search "auth"        # full-text + semantic search

3. Browse with the dashboard

codemark tui

See the Full Command Reference for every subcommand and flag — including collections, tours, snippet matching, and multi-repo queries.

---

🌐 Supported Languages

Codemark speaks AST for:

• 🦀 Rust
• 🍎 Swift
• 🔷 TypeScript / TSX
• 🐍 Python
• 🐹 Go
• ☕ Java
• 🎯 Dart
• ♯ C#

---

🎨 Customizing Markdown Output

Codemark formats command output and TUI previews with Handlebars templates. Override the default for codemark show (and the TUI panes) by dropping your own template in the config directory:

mkdir -p ~/.config/codemark/templates
cp ./templates/codemark_show.md ~/.config/codemark/templates/
$EDITOR ~/.config/codemark/templates/codemark_show.md

For the full template specification — every available variable, loops, conditionals, helpers, and the default templates — see the Templates reference.

---

📖 Documentation

• Full Command Reference — Detailed flag and subcommand guide.
• Configuration — Editor setup, themes, global/local config, and semantic search.
• Templates — Customize markdown output and TUI previews.
• Agent Workflow Guide — End-to-end walkthrough of using Codemark with an AI agent.
• Agent Skill — The skill installed by codemark install-skill (Claude Code, Copilot, Gemini, and more).

---

🏗️ Built With

Codemark is a local-first Rust workspace — no cloud service, account, or API key is required for any core feature.

Layer	Technology
Language	Rust (workspace: codemark-core, codemark-cli, codemark-tui, codetours-server)
Structural parsing	tree-sitter
Storage	SQLite via rusqlite (bundled), with sqlite-vec for vector search and FTS5 for full-text search
Embeddings	Local models run on candle — semantic search with no API key
TUI	ratatui + crossterm, with syntect syntax highlighting
Templating	Handlebars
Sync server	axum + tokio, JWT auth (the codetours server)
Git integration	git2 (libgit2)

---

🛡️ License

Released under the MIT License.