The Problem

Working with an LLM agent on a complex problem often means iterating across multiple files, considering alternatives, making decisions, and building understanding over time. But when the conversation ends, you're left with a wall of chat history and modified files—no clear trail of where you went and why.

Clawmarks solves this by letting agents drop annotated bookmarks as they work. These clawmarks capture the narrative of your exploration: decision points, open questions, alternatives considered, and how they all connect. The result is a navigable map of your coding session, not just a transcript.

What It Does

Clawmarks is an MCP server that gives LLM agents tools to create annotated bookmarks in your codebase. Clawmarks are organized into trails (narrative journeys), can reference each other (knowledge graph style), and are stored in a simple JSON file that any editor can consume.

Each clawmark captures:

• Where - File, line, column
• What - An annotation explaining why this location matters
• Type - Decision, question, change needed, alternative approach, etc.
• Connections - References to other clawmarks (knowledge graph edges)
• Context - Tags and trail groupings

Quick Start

1. Install globally:

   npm install -g clawmarks

2. Add .clawmarks.json to your global gitignore (one-time setup):

   echo ".clawmarks.json" >> ~/.gitignore_global
   git config --global core.excludesfile ~/.gitignore_global

3. Add the MCP server:

   Option A: Claude CLI (recommended)

   claude mcp add --scope user clawmarks -- clawmarks mcp

   Option B: Manual configuration

   Add to your project's .mcp.json:

   {
     "mcpServers": {
       "clawmarks": {
         "command": "clawmarks",
         "args": ["mcp"]
       }
     }
   }

The server stores .clawmarks.json in the current working directory. To override the project root:

claude mcp add --scope user clawmarks -- clawmarks mcp --env CLAWMARKS_PROJECT_ROOT=/path/to/project

Or in .mcp.json:

{
  "mcpServers": {
    "clawmarks": {
      "command": "clawmarks",
      "args": ["mcp"],
      "env": {
        "CLAWMARKS_PROJECT_ROOT": "/path/to/project"
      }
    }
  }
}

MCP Tools

Trail Management

| Tool | Description | |------|-------------| | create_trail | Create a new trail to organize related clawmarks | | list_trails | List all trails (optionally filter by status) | | get_trail | Get trail details with all its clawmarks | | archive_trail | Archive a completed trail |

Clawmark Management

| Tool | Description | |------|-------------| | add_clawmark | Add an annotated bookmark at a file location | | update_clawmark | Update clawmark metadata | | delete_clawmark | Remove a clawmark | | list_clawmarks | List clawmarks with optional filters |

Knowledge Graph

| Tool | Description | |------|-------------| | link_clawmarks | Create a reference from one clawmark to another | | unlink_clawmarks | Remove a reference | | get_references | Get all clawmarks connected to a clawmark | | list_tags | List all tags used across clawmarks |

Clawmark Types

• decision - A decision point that was made
• question - Open question needing resolution
• change_needed - Code that needs modification
• reference - Reference point (existing code to understand)
• alternative - Alternative approach being considered
• dependency - Something this depends on

Data Format

Clawmarks stores data in .clawmarks.json:

{
  "version": 1,
  "trails": [
    {
      "id": "t_abc123",
      "name": "Auth Refactor Options",
      "description": "Exploring JWT vs session-based auth",
      "status": "active",
      "created_at": "2025-12-17T10:30:00Z"
    }
  ],
  "clawmarks": [
    {
      "id": "c_xyz789",
      "trail_id": "t_abc123",
      "file": "src/auth/handler.ts",
      "line": 42,
      "column": 8,
      "annotation": "Current session logic - could replace with JWT",
      "type": "alternative",
      "tags": ["#security", "#breaking-change"],
      "references": ["c_def456"],
      "created_at": "2025-12-17T10:31:00Z"
    }
  ]
}

Editor Integrations

The .clawmarks.json file is designed to be consumed by any editor or tool.

| Editor | Plugin | |--------|--------| | Neovim | clawmarks.nvim | | VS Code | Coming soon | | Emacs | Contributions welcome |

Example Usage

In a conversation with your LLM agent:

"Let's explore two approaches to refactoring the auth system. Can you create a trail and mark the key decision points?"

The agent will:

1. Create a trail called "Auth Refactor Options"
2. Add clawmarks at relevant code locations
3. Link related clawmarks together
4. Tag clawmarks with relevant concerns

You can then browse these clawmarks in your editor to revisit the exploration's journey through your code.

License

MIT