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.
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.
When starting a session, inject a summary of active bookmarks:
codemark list --status active
If the user invoked you with arguments (e.g. /codemark something), use $ARGUMENTS to search the active bookmarks or execute the desired behavior:
codemark search "$ARGUMENTS"codemark show "$ARGUMENTS"codemark open "$ARGUMENTS"When the user asks about something, try these strategies in order:
Best for natural language queries and conceptual searches:
codemark search "user query" --semantic
When the user mentions specific concepts or categories:
codemark list --tag feature:auth --tag role:entrypoint
codemark list --tag layer:api --status active
codemark list --tag type:config --author agent
When discussing specific files or modules:
codemark list --file src/auth.rs --status active
codemark list --file src/auth.rs --lang rust
When exploring a feature or workflow:
codemark collection list
codemark collection show <collection-name>
For best results, combine semantic search with filters:
codemark search "authentication" --lang rust --author agent
codemark search "middleware" --tag layer:api --status active
| 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 | collection browse |
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.
--created-by agent vs default user).Use structured, colon-prefixed tags for powerful filtering. Combine multiple tags to create precise filters.
Identify which feature or domain area the bookmark belongs to.
feature:<name> — e.g., feature:auth, feature:logging, feature:paymentsdomain:<name> — e.g., domain:user-management, domain:analyticsIdentify the architectural layer or component boundary.
layer:api — HTTP handlers, API endpoints, controllerslayer:business — Business logic, domain services, use caseslayer:data — Database queries, repositories, data accesslayer:infra — Infrastructure, external services, I/Olayer:ui — UI components, views, presentation logiclayer:config — Configuration, constants, environment setupIdentify the primary role or responsibility of the code.
role:entrypoint — Application entry points, main functionsrole:handler — Request handlers, event handlersrole:service — Service layer, business logicrole:repository — Data access, database operationsrole:middleware — Middleware, interceptors, filtersrole:validator — Validation, verification logicrole:transformer — Data transformation, mapping, conversionrole:config — Configuration loading/parsingrole:constant — Constants, enums, static valuesrole:error — Error handling, error typesrole:test — Test utilities, fixtures, test helpersrole:utility — Helper functions, utilitiesIdentify the kind of code element.
type:function — Functions, methodstype:class — Classes, structstype:interface — Interfaces, protocols, traitstype:enum — Enums, unionstype:constant — Constants, literalstype:module — Modules, packagesIdentify the state or lifecycle of the bookmarked code.
status:active — Currently in usestatus:deprecated — Deprecated, planned for removalstatus:experimental — Experimental, may changestatus:stable — Stable, unlikely to changeLink bookmarks to specific tasks or work items.
task:<id> — e.g., task:fix-123, task:refactor-authpr:<number> — Associated pull requestissue:<number> — Associated issueIdentify risk level or sensitivity.
risk:high — High risk, changes require careful reviewrisk:medium — Medium riskrisk:low — Low risk, safe to modifyIdentify security-sensitive code.
security:auth — Authentication, authorizationsecurity:crypto — Encryption, hashing, cryptographysecurity:validation — Input validation, sanitizationsecurity:sensitive — Accesses sensitive data# 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 --tag risk:high
# Configuration
--tag layer:config --tag role:constant --tag status:stable
Always include the module or package context from the file path. Each language ecosystem has its own conventions—use the appropriate tag format.
module:<name> — Swift Package Manager module nameSources/<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 |crate:<name> — For workspace crates (e.g., crates/)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 |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 |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 |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 |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 |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 |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 crates/auth/src/lib.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
Use --collection when creating bookmarks to add them directly to a collection:
codemark add --file src/auth.rs --range 42 --note "Core auth entry point: Handles all JWT verification" --tag feature:auth --tag role:entrypoint --created-by agent --collection login-flow
codemark add-from-query --file src/auth.swift --query '(function_declaration name: (simple_identifier) @name (#eq? @name "validateToken")) @target' --note "Validates JWT tokens" --created-by agent --collection login-flow
codemark collection show login-flow
When you know the file and line numbers:
codemark add --file src/auth.rs --range 42 --note "Core auth entry point: Handles all JWT verification" --context "Module: auth | Validates all JWT tokens for API requests" --tag module:auth --tag feature:auth --tag role:entrypoint --created-by agent
When you have the code snippet but need to find it in a file:
echo "func validateToken(_ token: String) -> Claims" | codemark add-from-snippet --file src/auth.swift --note "Validates JWT tokens" --context "Module: auth | JWT validation with expiry check" --tag module:auth --tag feature:auth --tag role:validator --created-by agent
When you want precise control over what gets bookmarked:
codemark add-from-query --file src/auth.swift --query '(function_declaration name: (simple_identifier) @name (#eq? @name "validateToken")) @target' --note "Validates JWT tokens" --context "Module: auth | Core validation logic" --tag module:auth --tag feature:auth --tag role:validator --created-by agent
For common query patterns across languages, see:
queries/swift.mdqueries/rust.mdqueries/typescript.mdqueries/python.mdqueries/go.mdqueries/java.mdqueries/csharp.mdqueries/dart.mdqueries/common.md — Cross-language patterns and strategies--created-by agent to distinguish your bookmarks from the user's.--collection <name> when creating bookmarks to add them directly to a collection (collections are auto-created if they don't exist).annotate to add notes without re-parsing the file. Multiple agents can annotate the same bookmark over time.templates.md.examples.md.queries/ directory for language-specific guides.# By range (line or byte) — optionally add to collection
codemark add --file src/auth.rs --range 42:67 --collection my-work
# By code snippet (searches for snippet in file) — optionally add to collection
codemark add-from-snippet --file src/auth.rs --collection my-work
# By raw tree-sitter query (most precise) — optionally add to collection
codemark add-from-query --file src/auth.rs --query '(function_declaration) @target' --collection my-work
# Preview what would be bookmarked (dry-run)
codemark add --file src/auth.rs --range 42 --dry-run
codemark resolve --status active
codemark list --author agent
codemark search "authentication"
# 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}"
# Collections are auto-created when using --collection, or create explicitly:
codemark collection create login-flow --description "Step-by-step login execution path"
# Show bookmarks in a collection
codemark collection show login-flow
# List all collections
codemark collection list
codemark diff --since HEAD~3
# Add notes, context, or tags to an existing bookmark
codemark annotate <bookmark-id> --note "Additional context discovered during implementation"
codemark annotate <bookmark-id> --context "Related to auth-refactor feature"
codemark annotate <bookmark-id> --tag bug-fix --tag priority:high
# Add annotation as an agent with provenance
codemark annotate <bookmark-id> --note "Found this during debugging the session timeout issue" --added-by agent --source investigation
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.
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 |
Explain which business domain or bounded context this code belongs to.
codemark annotate <id> --context "Domain: User authentication | Bounded context: Identity and Access Management"
Document where and how this code is used.
codemark annotate <id> --context "Used by: API middleware, websocket handler, cron jobs"
Track the lifecycle and evolution of the code.
codemark annotate <id> --context "Added in: v2.3.0 | Deprecated in: v3.0.0 | Replacement: src/auth/v2/"
Document risk level and change impact.
codemark annotate <id> --context "Risk: High | Change impact: Affects all authenticated routes | Requires: Security review"
Link to related bookmarks and dependencies.
codemark annotate <id> --context "Depends on: [[bookmark-id-claims]] | Called by: [[bookmark-id-middleware]]"
Note performance characteristics when relevant.
codemark annotate <id> --context "Performance: O(n) where n = user roles | Cache: 30s TTL"
For security-sensitive code, document security considerations.
codemark annotate <id> --context "Security: Validates JWT signature | Checks expiry | Handles token rotation"
When creating or annotating bookmarks, use this template:
Context: <domain> | <usage> | <dependencies> | <risk/security/evolution notes>
Examples:
Context: Auth domain | Validates all API requests | Depends on Claims struct | Risk: highContext: Payment processing | Called by checkout flow | External: Stripe API | Risk: criticalContext: User preferences | Cached 30s | DB: users_table | Low riskcodemark heal --auto-archive
codemark status
Swift, Rust, TypeScript, Python, Go, Java, C#, Dart.