README.md

August 13, 2026 · View on GitHub

Native on

Codemark bookmarks code by structure, not by line number. A file:line reference breaks the moment you add a newline above it; Codemark uses tree-sitter to remember what you marked (a function, a block, a type) and anchors the bookmark to that named structure, so it still points at the right place after you refactor or reformat around it.

That durability is what makes it useful for long agent sessions, code audits, and keeping track of things you want to find again.

⚡ Use It With Your Agent

Codemark ships with a skill you can install into your coding agent. Once it's in, the agent knows how to create and recall structural bookmarks on its own, so the context it built up in one session is still there in the next, instead of being rebuilt from scratch every time.

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, in a fresh session and even after the code has moved around, you or another agent can pick the context back up:

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

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

What you can ask for

Once a flow lives in a collection, anyone can reuse it: you, a teammate, or the next agent session:

🧭 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 comes with a keyboard-driven dashboard in the style of lazygit. It's the main way to browse and manage bookmarks, collections, and tours by hand.

codemark tui

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

Browsing bookmarks in the TUI

🎬 More demos

_{Settings overlay}

_{FTS & semantic search}

_{Filter pane contents}

_{Resize & cycle layouts}

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, with 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: Queries are anchored to named structures and survive refactoring and reformatting 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

codemark tui opens the interactive dashboard. The prebuilt codemark binary (script, PowerShell, mise) and Homebrew all bundle the dashboard, so it works out of the box with no extra install.

If you build a lean CLI from source with --no-default-features (dropping the bundled TUI), codemark tui instead looks for a standalone codemark-tui on your PATH; add it 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, with 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 is powered by Tree-sitter. It supports 8 built-in languages out of the box, and any other language via dynamic WASM grammar loading.

Built-in:

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

Dynamic (WASM)

You can add support for any language without recompiling Codemark. Drop a compiled Tree-sitter .wasm grammar together with a manifest.json into Codemark's grammar cache directory (e.g., ~/Library/Caches/codemark/grammars/<language>/ on macOS), and Codemark will discover it on the next run.

The manifest.json isn't optional — it tells Codemark how to load and query the grammar (node kinds, symbol mappings, and metadata). For the full manifest schema and a step-by-step walkthrough, see the Dynamic Grammars guide.

🎨 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, covering 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` for semantic search with no API key
TUI	`ratatui` + `crossterm`, with `syntect` syntax highlighting
Markdown	`pulldown-cmark` renders the details and collection-overview previews
Templating	Handlebars
Sync server	`axum` + `tokio`, JWT auth (the `codetours` server)
Git integration	`git2` (libgit2)

🛡️ License

Released under the MIT License.