Agent Breadcrumbs 🍞

1# Agent Breadcrumbs 🍞
2 
3Lightweight logging & observability for agent work across clients (Codex, Claude, Cursor, ChatGPT, OpenClaw, and others).
4 
5https://github.com/user-attachments/assets/3eac31a8-107c-4a82-a14c-dcfa500dd1a9
6 
7## What You Get
8 
9- One MCP tool (`log_work`) that aggregates work done across different agents for single or multiple users.
10- Define your own logging structure with custom schemas (or use built-in profiles) once, and the MCP schema 
11will guide clients to log with correct payloads. 
12- This lets teams standardize logging once, then route data wherever they need it.
13- Multiple options for output sinks:
14  - local JSONL
15  - webhook
16  - Postgres
17- Starter schema profiles for common use cases:
18  - agent insights
19  - delivery tracking
20  - audit trail
21  - knowledge capture
22- Simple dashboard app to view logged work.
23 
24## Repository Layout
25 
26- MCP server package (published): `packages/mcp`
27- Dashboard app (repo-local, not published): `apps/dashboard`
28 
29## Quick Start (MCP)
30 
31Install and run with defaults:
32 
33```bash
34npx -y agent-breadcrumbs
35```
36 
37Use with an explicit config file:
38 
39```bash
40npx -y agent-breadcrumbs --config /absolute/path/to/server-config.json
41```
42 
43### Codex config example (`~/.codex/config.toml`):
44```toml
45[mcp_servers.agent_breadcrumbs]
46command = "npx"
47args = ["-y", "agent-breadcrumbs", "--config", "/absolute/path/to/server-config.json"]
48```
49 
50`--config` is optional. If omitted, server defaults are used:
51 
52<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" />
53<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" />
54 
55### Claude Desktop (`claude_desktop_config.json`):
56```json
57{
58  "mcpServers": {
59    "agent-breadcrumbs": {
60      "command": "npx",
61      "args": ["-y", "agent-breadcrumbs", "--config", "/absolute/path/to/server-config.json"]
62    }
63  }
64}
65```
66 
67<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" />
68 
69### OpenClaw:
70After you install the MCP server make sure to use mcporter so the server can be called through the CLI. 
71Then add a system prompt to the channel you're using.
72 
73<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" />
74 
75For cron-driven workflows, instruct agents to call log_work on each scheduled run
76for regular time-based logging.
77 
78```text
79Every hour, make sure to use mcporter agent-breadcrumbs.log_work to log work.
80If spinning up a cron job, make sure to add this context (e.g., logging work every hour) in the cron job description as well.
81```
82 
83General example global instruction/system prompt for clients:
84 
85```text
86When a meaningful chunk of work is completed, use log_work with agent_breadcrumbs to record your work.
87```
88 
89For full MCP server setup, config, and sink details, see `packages/mcp/README.md`.
90 
91## Quick Start (Repo)
92 
93```bash
94npm install
95npm run build:all
96```
97 
98Run MCP server locally with a sample config:
99 
100```bash
101node packages/mcp/dist/index.js --config packages/mcp/examples/server-config.agent-insights.sample.json
102```
103 
104Run dashboard locally:
105 
106```bash
107npm run dev:dashboard -- --config apps/dashboard/examples/dashboard-config.sample.json
108```
109 
110## MCP Config Model
111 
112Top-level config file is JSON and supports:
113 
114- `schema` for fully custom `log_record` properties, or
115- `schema_profile` for built-in profile files in `packages/mcp/examples/schema_profiles`
116- `user_name` for server-side user identity injection into persisted records
117- `sink` for destination settings (`jsonl`, `webhook`, `postgres`)
118 
119Do not set both `schema` and `schema_profile` together.
120 
121Default behavior when omitted:
122 
123- schema: built-in default (`agent_id`, `timestamp`, `work_summary`, `additional`)
124- sink: `jsonl`
125- output file: `~/.agent-breadcrumbs/logs.jsonl`
126- user_name: not injected
127 
128## Why Config
129 
130- Your schema/profile is applied directly to the MCP tool input schema.
131- Agent clients see the required `log_record` fields from the tool definition.
132- You do not need to repeatedly explain payload format for every tool call in client.
133 
134## Common Commands
135 
136```bash
137npm run build:mcp
138npm run dev:mcp
139npm run test
140npm run test:integration
141npm run build:dashboard
142npm run dev:dashboard
143```
144 
145## Docs
146 
147- MCP package docs: `packages/mcp/README.md`
148- Dashboard app docs: `apps/dashboard/README.md`
149