Bookmarks that
survive refactors.

In the age of AI, being in your editor is less important.
Codemark lets you map out the critical parts of your codebase, providing a structured memory that lets you jump into the editor only when needed.

Quick Start Installation

~/project/codemark

# Bookmark a function securely
$ codemark add --file src/auth.rs --range 42 --tag auth --note "Token validation"
✔ Added bookmark 'a1b2c3d' for validate_token in src/auth.rs

# Refactor happens... lines shift... function is renamed...

# Resolve — finds where the code is *now*
$ codemark resolve a1b2
src/auth.rs:89:15 (Match: Relaxed)

# Search semantically using local embeddings
$ codemark search --semantic "database connection initialization"
b8x9z2 | src/db.rs:12 | init_pool | score: 0.89

Why use Codemark?

Traditional bookmarks are brittle. Codemark uses abstract syntax trees to understand your code the way a compiler does.

In the era of AI, we spend more time orchestrating and reviewing than writing line-by-line. Codemark provides the structural memory needed to navigate complex systems without getting lost in the noise.

Durable References

Bookmarks identify code structurally. A renamed function is still found even if it moved across the file.

Self-Healing

Layered resolution (exact match → relaxed query → content hash fallback) degrades gracefully rather than breaking silently.

Unix Philosophy

Produces line-oriented, pipe-friendly JSON output. Integrates naturally with fzf, bat, and shell scripts.

Semantic Search

Query "where's the auth logic?" using local vector embeddings (powered by sqlite-vec). No external API calls needed.

Collections

Group related bookmarks into named sets for bugfixes or feature investigations, ready to load across sessions.

Multi-Language

Auto-detects and parses Rust, Swift, TypeScript, Python, Go, Java, C#, and Dart files seamlessly.

Beyond Simple Line Numbers

Feature	Standard IDE Bookmarks	Codemark
Refactor Resilience	❌ Breaks on line shifts	✅ Survives renames & moves
Semantic Search	❌ Literal text only	✅ Local Vector Embeddings
Rich Metadata	❌ Minimal	✅ Notes, Tags, & Authors
Agent Integration	❌ UI-only	✅ LLM-Native Skills
Organization	❌ Flat list	✅ Collections & Workspaces

Metadata & Contextual Memory

A bookmark is more than just a pointer. It's a container for knowledge. Codemark allows you to attach rich metadata to any piece of code, creating a searchable map of your project's architecture.

Notes & Rationale:
Explain *why* a piece of code exists, its side effects, or known debt.
Categorization:
Apply tags like #auth, #vulnerability, or #entrypoint.
Hierarchical Collections:
Group bookmarks into named sets for feature development or bug investigations.

codemark show a1b2 --format json

{
  "id": "a1b2c3d",
  "data": {
    "file_path": "src/auth.rs",
    "line_range": "42:67",
    "note": "Critical JWT validation logic. Contact security team before modifying.",
    "tags": ["auth", "security", "entrypoint"],
    "created_by": "daniel",
    "collection": "security-audit-2024"
  }
}

Installation

Codemark is a self-contained Rust binary with no runtime dependencies. Requires Rust 1.75+.

macOS / Linux (Homebrew)

brew tap DanielCardonaRojas/codemark
brew install codemark

rs Rust (Cargo)

cargo install --path .

LLM Agent Skills

Codemark isn't just for humans. It provides a structured "memory" for AI agents. By providing a SKILL.md, agents can autonomously bookmark critical discovery paths, helping them maintain context across long-running tasks.

# Agent discovers auth logic
$ codemark add --range 42 --author agent --note "Observed entrypoint"
✔ Bookmarked 'a1b2' for later reference

Television TUI

The recommended way to browse bookmarks. Navigate your codebase at the speed of thought with the Television channel.

🔍 Fuzzy find across all your bookmarks
📺 Toggle between code and markdown previews
🚀 Open directly in your configured editor
📋 Copy snippets to clipboard with Ctrl-C
🗃️ Switch between bookmark collections

# Launch interactive TUI
$ tv codemark
# Press Ctrl-C to copy resolved code
| a1b2 | src/auth.rs | JWT Logic |

Common Workflows

1. Adding a bookmark

# By line range (most common)
codemark add --file src/auth.rs --range 42
codemark add --file src/auth.rs --range 42:67

# Preview what would be bookmarked (dry run)
codemark add --file src/auth.rs --range 42:67 --dry-run

2. Browsing and Previewing (Piping Output)

# List all bookmarks
codemark list

# Preview outputs JSON for easy piping to your editor or viewer:
codemark preview a1b2 | jq -r '"bat --highlight-line \(.data.line_range) \(.data.file_path)"' | sh

# NEW: Output RAW content to stdout (great for copy/paste or scripts)
codemark preview a1b2 --raw | pbcopy

3. Health Management

# See the health of your codebase memory
codemark status
# 42 active | 3 drifted | 1 stale | 0 archived

# Re-resolve all and update statuses
codemark validate

Bookmarks that survive refactors.