codemark

name	codemark
description	Manage structural code bookmarks that survive refactoring. Use when the user says "remember this", "bookmark this", "save this location", "load my bookmarks", "what do I have bookmarked", "mark this code", "codemark", or when starting a new session and needing to reload context from a previous session. Also use proactively when you discover critical code during exploration — entry points, boundaries, configuration, error handling — that you'd want to remember if starting over.
allowed-tools	Bash(codemark *)

Codemark — Structural Code Bookmarking

You have access to codemark, a CLI tool that creates structural bookmarks for code using tree-sitter AST queries. Unlike file:line references, these bookmarks survive renames, refactors, and reformatting.

Active Context

When starting a session, inject a summary of active bookmarks:

codemark list --health active

Agent Directives: Handling Invocations

If the user invoked you with arguments (e.g. /codemark something), use $ARGUMENTS to search the active bookmarks or execute the desired behavior:

• Search text: codemark search "$ARGUMENTS"
• If it looks like a bookmark ID or UUID prefix: codemark show "$ARGUMENTS"
• If user asks to "open", "edit", or view a bookmark: codemark open "$ARGUMENTS"
• If no arguments were provided, interpret the user's intent based on the conversation context.

Intelligent Bookmark Discovery

When the user asks about something, try these strategies in order:

1. Semantic Search (Most Flexible)

Best for natural language queries and conceptual searches:

codemark search "user query" --semantic

2. Tag-Based Filtering

When the user mentions specific concepts or categories:

codemark list --tag feature:auth --tag role:entrypoint
codemark list --tag layer:api --health active
codemark list --tag type:config --author agent

3. File-Aware Search

When discussing specific files or modules:

codemark list --file src/auth.rs --health active
codemark list --file src/auth.rs --lang rust

4. Collection Browsing

When exploring a feature or workflow:

codemark tour list
codemark tour show <collection-name>

5. Hybrid Search Pattern

For best results, combine semantic search with filters:

codemark search "authentication" --lang rust --author agent
codemark search "middleware" --tag layer:api --health active

Discovery Strategy Summary

User Query Type	Primary Strategy	Fallback
"Show my auth bookmarks"	--tag feature:auth	semantic search
"Where's the config?"	--tag type:config	--tag role:config
"Bookmarks in auth.rs"	--file src/auth.rs	semantic search
"Recent agent bookmarks"	--author agent	semantic search
"What did I mark for X?"	semantic search	tour browse

When to use codemark

• Starting a session: Load bookmarks from a previous session to restore context.
• Exploring code: When you discover something critical, bookmark it with context about why it matters.
• During work: Bookmark code you'll need to reference later — especially cross-file relationships.
• Ending a session: Validate bookmarks so the next session has accurate references.
• Checking impact: Use codemark tour diff to see which bookmarks are affected by recent changes.

Proactive bookmarking: When you recognize code that is critical to the current task — entry points, auth boundaries, error handling paths, configuration — bookmark it immediately with a note explaining its significance and relationship to the work. Don't bookmark everything you read; bookmark what you'd want to know if starting over tomorrow.

Key Concepts

• Bookmarks store a tree-sitter query that identifies code by AST structure, not line numbers.
• Resolution re-finds bookmarked code even after edits (exact → relaxed → hash fallback).
• Tours/Collections group related bookmarks (one per feature, bugfix, or investigation).
• Health: active (healthy), drifted (found but moved), stale (lost), archived (cleaned up).
• Author: bookmarks track who created them (--created-by agent vs default user).
• Annotations: bookmarks can have multiple annotations (notes, context) added by different agents over time, with provenance tracking. Use --note multiple times to add several notes at once.

Tag Taxonomy

Use structured, colon-prefixed tags for powerful filtering. Combine multiple tags to create precise filters.

Feature/Domain Tags

Identify which feature or domain area the bookmark belongs to.

• feature:<name> — e.g., feature:auth, feature:logging, feature:payments
• domain:<name> — e.g., domain:user-management, domain:analytics

Architectural Layer Tags

Identify the architectural layer or component boundary.

• layer:api — HTTP handlers, API endpoints, controllers
• layer:business — Business logic, domain services, use cases
• layer:data — Database queries, repositories, data access
• layer:infra — Infrastructure, external services, I/O
• layer:ui — UI components, views, presentation logic
• layer:config — Configuration, constants, environment setup

Role/Responsibility Tags

Identify the primary role or responsibility of the code.

• role:entrypoint — Application entry points, main functions
• role:handler — Request handlers, event handlers
• role:service — Service layer, business logic
• role:repository — Data access, database operations
• role:middleware — Middleware, interceptors, filters
• role:validator — Validation, verification logic
• role:transformer — Data transformation, mapping, conversion
• role:config — Configuration loading/parsing
• role:constant — Constants, enums, static values
• role:error — Error handling, error types
• role:test — Test utilities, fixtures, test helpers
• role:utility — Helper functions, utilities

Type Tags

Identify the kind of code element.

• type:function — Functions, methods
• type:class — Classes, structs
• type:interface — Interfaces, protocols, traits
• type:enum — Enums, unions
• type:constant — Constants, literals
• type:module — Modules, packages

Task/Work Tags

Link bookmarks to specific tasks or work items.

• task:<id> — e.g., task:fix-123, task:refactor-auth
• pr:<number> — Associated pull request
• issue:<number> — Associated issue

Security Tags

Identify security-sensitive code.

• security:auth — Authentication, authorization
• security:crypto — Encryption, hashing, cryptography
• security:validation — Input validation, sanitization
• security:sensitive — Accesses sensitive data

Recommended Tag Combinations

# Auth entry point
--tag feature:auth --tag layer:api --tag role:entrypoint --tag security:auth

# Database query
--tag feature:users --tag layer:data --tag role:repository

# Business logic
--tag feature:payments --tag layer:business --tag role:service

# Configuration
--tag layer:config --tag role:constant

Module/Package Tags (Language-Specific)

Always include the module or package context from the file path. Each language ecosystem has its own conventions—use the appropriate tag format.

Swift

• Tag: module:<name> — Swift Package Manager module name
• Inference: From Sources/<ModuleName>/ or target name in Package.swift | File path | Module tag | |-----------|------------| | Sources/AuthService/Validator.swift | --tag module:AuthService | | Sources/App/Models/User.swift | --tag module:App |

Rust

• Tag: crate:<name> — For workspace crates (e.g., crates/)
• Tag: module:<name> — For modules within src/ | File path | Module tag | |-----------|------------| | crates/auth/src/lib.rs | --tag crate:auth | | crates/auth/src/service.rs | --tag crate:auth --tag module:service | | src/auth/mod.rs | --tag module:auth | | src/auth/service.rs | --tag module:auth |

Go

• Tag: package:<path> — Full package path relative to module root | File path | Module tag | |-----------|------------| | internal/auth/handler.go | --tag package:internal.auth | | pkg/api/middleware.go | --tag package:pkg.api | | cmd/server/main.go | --tag package:cmd.server | | handler.go (root) | --tag package:root |

Python

• Tag: package:<path> — Python package path (dot notation) | File path | Module tag | |-----------|------------| | app/auth/service.py | --tag package:app.auth | | src/backend/db/models.py | --tag package:src.backend.db | | tests/test_auth.py | --tag package:tests |

TypeScript / JavaScript

• Tag: module:<name> — Directory or workspace package name | File path | Module tag | |-----------|------------| | src/auth/service.ts | --tag module:auth | | packages/backend/src/db.ts | --tag module:backend | | components/auth/Login.tsx | --tag module:components.auth | | lib/api/client.ts | --tag module:lib.api |

Java

• Tag: package:<name> — Java package name (dot notation) | File path | Module tag | |-----------|------------| | com/app/auth/AuthService.java | --tag package:com.app.auth | | org/mycompany/api/handler.java | --tag package:org.mycompany.api |

C#

• Tag: namespace:<name> — C# namespace | File path | Module tag | |-----------|------------| | App.Auth/Services/AuthService.cs | --tag namespace:App.Auth.Services | | MyCompany.Data/Repositories/UserRepo.cs | --tag namespace:MyCompany.Data.Repositories |

Dart

• Tag: package:<name> — Dart package name | File path | Module tag | |-----------|------------| | lib/auth/service.dart | --tag package:auth | | lib/models/user.dart | --tag package:models |

Example (Rust crate):

codemark add --file src/auth.rs --range 10 --note "Core JWT validation" --tag crate:auth --tag feature:auth --tag layer:business --tag role:validator

Example (Go package):

codemark add --file internal/auth/handler.go --range 25 --note "HTTP handler for authentication" --tag package:internal.auth --tag feature:auth --tag layer:api --tag role:handler

Quick Start

IMPORTANT: The codemark add command requires --file <path> for all operations. The file path is NOT a positional argument.

Creating a tour/collection of bookmarks (recommended for agents)

Use --collection when creating bookmarks to add them directly to a tour. Always prefer range-based targeting as the first resource. You can add multiple notes using --note multiple times:

# 1. Preferred: Range-based targeting (Line or Point)
codemark add --file src/auth.rs --range 42 --note "Core auth entry point" --note "Handles JWT validation" --collection login-flow

# 2. Alternative: Snippet-based (if range is unknown)
echo "func validateToken" | codemark add --file src/auth.swift --snippet --note "Validates JWT tokens" --note "Critical for security" --collection login-flow

# 3. Last Resort: Raw tree-sitter query (for extreme precision/disambiguation)
codemark add --file src/auth.swift --query '(function_declaration) @target' --note "Token validation function" --note "Called by middleware" --collection login-flow

# With context attached to first note
codemark add --file src/auth.rs --range 42 --note "Auth entry point" --context "Part of login refactor" --note "Needs review" --collection login-flow

codemark tour show login-flow

Method 1: Range-based bookmarking (Primary Resource)

When you know the file and line numbers. This leverages the Anchored Precision engine to automatically generate stable, architecturally-anchored queries.

# Point targeting: targets the smallest node at line 42, column 10
codemark add --file src/auth.rs --range 42:10 --note "Specific authorization gate" --created-by agent

# Line targeting: targets the tightest node containing line 42
codemark add --file src/auth.rs --range 42 --note "Core auth entry point" --created-by agent

# Span targeting: targets a specific range of lines
codemark add --file src/auth.rs --range 42-67 --note "Full login method" --created-by agent

# Precise Span targeting: targets a specific range of characters
codemark add --file src/auth.rs --range 10:5-10:20 --note "Specific expression" --created-by agent

Method 2: Snippet-based bookmarking

When you have the code snippet but need to find it in a file:

echo "func validateToken(_ token: String) -> Claims" | codemark add --file src/auth.swift --snippet --note "Validates JWT tokens" --tag role:validator --created-by agent

Method 3: Raw tree-sitter query (Last Resort)

Use this only if range-based targeting is ambiguous or you need a highly specific non-positional pattern.

codemark add --file src/auth.swift --query '(function_declaration name: (simple_identifier) @name (#eq? @name "validateToken")) @target' --note "Validates JWT tokens" --created-by agent

For common query patterns across languages, see:

• queries/swift.md
• queries/rust.md
• queries/typescript.md
• queries/python.md
• queries/go.md
• queries/java.md
• queries/csharp.md
• queries/dart.md
• queries/common.md — Cross-language patterns and strategies

Best Practices

• Target small, specific code: Prefer single functions over entire classes, specific methods over whole modules. Smaller bookmarks are more resilient to refactoring, easier to understand, and more precise for navigation.
• Range-First Policy: Always prefer range-based targeting (--range) as your first choice. It leverages the unified "Anchored Precision" engine to generate stable, architecturally-anchored queries automatically. Only use raw tree-sitter queries (--query) as a last resort if range-based targeting is ambiguous.
• Fine-grained execution targeting: Don't just bookmark containers (classes/functions). Bookmark execution boundaries like critical method calls (call_expression), authorization gates (if_statement), or complex state transitions (switch/match).
• Granularity Strategy: We prefer more, highly specific bookmarks over fewer, general ones. For example, if a function performs three critical steps (auth, validation, DB write), it is better to bookmark those three specific lines/nodes than to bookmark the entire function.
• Use --created-by agent to distinguish your bookmarks from the user's.
• Use --collection <name> when creating bookmarks to add them directly to a tour (tours are auto-created if they don't exist).
• Iterative enhancement: When working with an existing bookmark and discover new context, use edit to add notes without re-parsing the file. Multiple agents can edit the same bookmark over time.
• For detailed note guidelines, see templates.md.
• For usage examples, see examples.md.
• For tree-sitter query patterns, see queries/ directory for language-specific guides.

Commands Reference

Creating bookmarks

# By range (line or byte) — optionally add to tour
codemark add --file src/auth.rs --range 42-67 --collection my-work

# By snippet (reads from stdin) — optionally add to tour
echo "snippet here" | codemark add --file src/auth.rs --snippet --collection my-work

# By raw tree-sitter query (most precise) — optionally add to tour
codemark add --file src/auth.rs --query '(function_declaration) @target' --collection my-work

# With multiple notes (each creates a separate annotation entry)
codemark add --file src/auth.rs --range 42-67 --note "Primary observation" --note "Secondary note" --note "Action item" --collection my-work

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

Viewing bookmarks

# Show bookmark with preview (default)
codemark show <bookmark-id>

# Show only file location (was 'resolve')
codemark show <bookmark-id> --location

# Show metadata only (no preview)
codemark show <bookmark-id> --no-preview

Load context

codemark list --health active
codemark list --author agent
codemark search "authentication"

Open bookmarked files

# Open a bookmark in your configured editor
codemark open <bookmark-id>

# The editor is configured via [open] section in .codemark/config.toml
# Supports placeholder substitution: {FILE}, {LINE_START}, {LINE_END}, {ID}
# Example: rs = "nvim +{LINE_START} {FILE}"

Organize with tours (collections)

# Tours are auto-created when using --collection, or create explicitly:
codemark tour create login-flow --description "Step-by-step login execution path"

# Create with tags, links, and notes in one command
codemark tour create auth-flow --tag feature:auth --link "https://docs.example.com/auth,Docs" --note "Main authentication flow"

# Show bookmarks in a tour
codemark tour show login-flow

# List all tours
codemark tour list

# Add bookmarks to a tour
codemark tour add login-flow <bookmark-id-1> <bookmark-id-2>

# Add with metadata
codemark tour add login-flow <bookmark-id> --tag implementation --note "Core handler"

# Annotate a tour (add tags, links, notes)
codemark tour annotate login-flow --tag phase:2 --link "https://example.com,Related"

# Publish a tour to Codetours
codemark tour push login-flow

# Pull a tour from Codetours
codemark tour pull <tour-url>

Editing bookmarks

# Add notes, context, or tags to an existing bookmark
codemark edit <bookmark-id> --note "Additional context discovered during implementation"
codemark edit <bookmark-id> --context "Related to auth-refactor feature"
codemark edit <bookmark-id> --tag bug-fix --tag priority:high

# Add multiple notes at once (each --note creates a separate annotation)
codemark edit <bookmark-id> --note "First observation" --note "Second observation" --note "Third insight"
codemark edit <bookmark-id> --note "Performance concern" --context "Investigation details" --note "Follow-up needed"

Health and maintenance

# Check bookmark health
codemark health status

# Run resolution (was 'heal')
codemark health check --auto-archive

# Remove old archived bookmarks
codemark health gc --older-than 30d

Data operations

# Export bookmarks
codemark data export --export-format json

# Import bookmarks
codemark data import backup.json

# Rebuild semantic search embeddings
codemark data reindex

Check impact

# See which bookmarks are affected by recent changes
codemark tour diff --since HEAD~3

Enriching Bookmark Context

High-quality context makes bookmarks discoverable and useful across sessions. Always enrich bookmarks with information that would help you or another agent find and understand the code later.

Module/Package Context (Required)

Always include module or package information inferred from the file path. This is critical for finding bookmarks by their location in the codebase.

# Infer from file path and add as context
codemark add --file src/auth/service.rs --range 42 --context "Module: auth | Package: service" --note "Core JWT validation" --tag module:auth

Language	Path pattern	Module context
Rust	crates/auth/src/lib.rs	crate:auth
Rust	src/auth/service.rs	module:auth
Go	internal/auth/handler.go	package:internal.auth
Python	app/auth/service.py	package:app.auth
TypeScript	src/auth/service.ts	module:auth
Java	com/app/auth/AuthService.java	package:com.app.auth
Swift	Sources/AuthService/	module:AuthService

Domain Context

Explain which business domain or bounded context this code belongs to.

codemark edit <id> --context "Domain: User authentication | Bounded context: Identity and Access Management"

Usage Context

Document where and how this code is used.

codemark edit <id> --context "Used by: API middleware, websocket handler, cron jobs"

Evolution Context

Track the lifecycle and evolution of the code.

codemark edit <id> --context "Added in: v2.3.0 | Deprecated in: v3.0.0 | Replacement: src/auth/v2/"

Dependency Context

Link to related bookmarks and dependencies.

codemark edit <id> --context "Depends on: [[bookmark-id-claims]] | Called by: [[bookmark-id-middleware]]"

Performance Context

Note performance characteristics when relevant.

codemark edit <id> --context "Performance: O(n) where n = user roles | Cache: 30s TTL"

Security Context

For security-sensitive code, document security considerations.

codemark edit <id> --context "Security: Validates JWT signature | Checks expiry | Handles token rotation"

Context Template

When creating or editing bookmarks, use this template:

Context: <domain> | <usage> | <dependencies> | <security/evolution notes>

Examples:

• Context: Auth domain | Validates all API requests | Depends on Claims struct
• Context: Payment processing | Called by checkout flow | External: Stripe API
• Context: User preferences | Cached 30s | DB: users_table

Supported languages

Swift, Rust, TypeScript, Python, Go, Java, C#, Dart.