agent-breadcrumbs

Agent Breadcrumbs 🍞

Lightweight logging & observability for agent work across clients (Codex, Claude, Cursor, ChatGPT, OpenClaw, and others).

https://github.com/user-attachments/assets/3eac31a8-107c-4a82-a14c-dcfa500dd1a9

What You Get

• One MCP tool (log_work) that aggregates work done across different agents for single or multiple users.
• Define your own logging structure with custom schemas (or use built-in profiles) once, and the MCP schema

will guide clients to log with correct payloads.

• This lets teams standardize logging once, then route data wherever they need it.
• Multiple options for output sinks:
• local JSONL
• webhook
• Postgres
• Starter schema profiles for common use cases:
• agent insights
• delivery tracking
• audit trail
• knowledge capture
• Simple dashboard app to view logged work.

Repository Layout

• MCP server package (published): packages/mcp
• Dashboard app (repo-local, not published): apps/dashboard

Quick Start (MCP)

Install and run with defaults:

npx -y agent-breadcrumbs

Use with an explicit config file:

npx -y agent-breadcrumbs --config /absolute/path/to/server-config.json

Codex config example (~/.codex/config.toml):

[mcp_servers.agent_breadcrumbs]
command = "npx"
args = ["-y", "agent-breadcrumbs", "--config", "/absolute/path/to/server-config.json"]

--config is optional. If omitted, server defaults are used:

<img width="1171" height="491" alt="Screenshot 2026-02-18 at 11 20 21 AM" src="https://github.com/user-attachments/assets/0340fa51-8ad0-4533-80df-e3b10166b0c6" /> <img width="1170" height="561" alt="Screenshot 2026-02-18 at 11 20 26 AM" src="https://github.com/user-attachments/assets/b5a8823b-68a1-4284-a4ed-2de9010efb1f" />

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "agent-breadcrumbs": {
      "command": "npx",
      "args": ["-y", "agent-breadcrumbs", "--config", "/absolute/path/to/server-config.json"]
    }
  }
}

<img width="1267" height="878" alt="Screenshot 2026-02-18 at 11 21 15 AM" src="https://github.com/user-attachments/assets/faa646f3-843a-4501-8d60-266e7f69b838" /><img width="1267" height="878" alt="Screenshot 2026-02-18 at 11 21 21 AM" src="https://github.com/user-attachments/assets/2e690d3c-4d9b-4370-a14d-2b8c5d95c33b" />

OpenClaw:

After you install the MCP server make sure to use mcporter so the server can be called through the CLI. Then add a system prompt to the channel you're using.

<img width="810" height="473" alt="Screenshot 2026-02-18 at 11 23 58 AM" src="https://github.com/user-attachments/assets/9fc7095d-9582-423f-822c-8e6926d458fb" />

For cron-driven workflows, instruct agents to call log_work on each scheduled run for regular time-based logging.

Every hour, make sure to use mcporter agent-breadcrumbs.log_work to log work.
If spinning up a cron job, make sure to add this context (e.g., logging work every hour) in the cron job description as well.

General example global instruction/system prompt for clients:

When a meaningful chunk of work is completed, use log_work with agent_breadcrumbs to record your work.

For full MCP server setup, config, and sink details, see packages/mcp/README.md.

Quick Start (Repo)

npm install
npm run build:all

Run MCP server locally with a sample config:

node packages/mcp/dist/index.js --config packages/mcp/examples/server-config.agent-insights.sample.json

Run dashboard locally:

npm run dev:dashboard -- --config apps/dashboard/examples/dashboard-config.sample.json

MCP Config Model

Top-level config file is JSON and supports:

• schema for fully custom log_record properties, or
• schema_profile for built-in profile files in packages/mcp/examples/schema_profiles
• user_name for server-side user identity injection into persisted records
• sink for destination settings (jsonl, webhook, postgres)

Do not set both schema and schema_profile together.

Default behavior when omitted:

• schema: built-in default (agent_id, timestamp, work_summary, additional)
• sink: jsonl
• output file: ~/.agent-breadcrumbs/logs.jsonl
• user_name: not injected

Why Config

• Your schema/profile is applied directly to the MCP tool input schema.
• Agent clients see the required log_record fields from the tool definition.
• You do not need to repeatedly explain payload format for every tool call in client.

Common Commands

npm run build:mcp
npm run dev:mcp
npm run test
npm run test:integration
npm run build:dashboard
npm run dev:dashboard

Docs

• MCP package docs: packages/mcp/README.md
• Dashboard app docs: apps/dashboard/README.md