DEV Community: Enmanuel Magallanes Pinargote

The Map Is Not the Territory — Dep-Aware Agent Between Explorer and Builder

Enmanuel Magallanes Pinargote — Fri, 05 Jun 2026 14:29:23 +0000

The intelligence problem

A reconnaissance team maps the territory on Monday. They produce a thorough report: entry points, structural layout, active systems, the works. It's accurate. They did their job well.

On Thursday, the strike team goes in with that report.

What nobody checked: on Tuesday, they rotated the guard shift. On Wednesday, someone welded the east door shut. The report is still 90% correct. The 10% is where things go wrong.

This is the operational gap that every intelligence agency, surgical team, and eventually every engineering org confronts: the distance between when analysis runs and when implementation starts is not zero. Things change in that gap. Nobody announces it. It doesn't feel like a change that matters.

Until it does.

Your Explorer's map goes stale

The standard harness workflow — Lead → Explorer → Builder → Reviewer — solves the right set of problems. Explorer maps the codebase so Builder doesn't go in blind. Builder implements against a real picture of the project, not a guess. Reviewer verifies before anything closes.

But Explorer produces a snapshot. It's accurate at the time it ran. The codebase it analyzed and the codebase Builder starts writing against are only guaranteed to be the same if nothing changed between the two sessions.

In practice, something almost always changes. A dependency gets bumped. A config shifts. Someone runs npm install before the next session starts. Nobody announces it. Doesn't feel significant.

Then drizzle-orm goes from 0.36 to 0.45 — a major bump — and Builder implements using query patterns that changed in the release. The Explorer's analysis was correct. The plan was solid. The code almost works. Nobody lied. Nobody missed a step. The workflow ran cleanly. The ground just shifted between phases and nobody checked.

That's the failure mode v1.6.4 is built to close.

A fifth role for a specific problem

The standard harness workflow has four roles: Lead (orchestrates), Explorer (reads and maps), Builder (implements), Reviewer (validates). Each has a defined permission scope. Each has a clear position in the chain.

The Consultant is a fifth role, but it's not part of the standard chain — it's conditional. Lead invokes it only when the situation warrants it:

When deps.check returns significant: true
When the task explicitly touches package.json, dependencies, or config files
When .harness/deps-lock.json doesn't exist yet (first task, no baseline)

For routine feature work with stable dependencies, the Consultant never enters the picture. The chain stays at four roles. The Consultant adds overhead only when that overhead is justified.

The MCP tools that make it work

Two new tools ship with v1.6.4, and both are exclusive to the Consultant role — no other agent can call them.

deps.snapshot

Captures the current state of package.json (both dependencies and devDependencies) and writes it to .harness/deps-lock.json with a timestamp. This is the baseline. It runs automatically the first time the Consultant is invoked on a fresh project.

{
  "capturedAt": "2026-06-05T10:23:00.000Z",
  "message": "Snapshot saved to .harness/deps-lock.json"
}

deps.check

Diffs the current package.json against the stored baseline. Returns a structured result:

{
  "significant": true,
  "added": ["zod@3.24.0"],
  "removed": [],
  "majorBumps": [
    { "name": "drizzle-orm", "from": "0.36.0", "to": "0.45.0" }
  ],
  "advisory": "Run npx autoskills to refresh agent skill files after dependency changes.",
  "snapshotDate": "2026-05-15T08:00:00.000Z"
}

significant: true means something changed that warrants a full Consultant pass. Minor patches and no-change cases return significant: false, and the Lead can skip the Consultant entirely.

What the Consultant actually produces

The Consultant's output is not a list of packages. It's structured advisory that the Builder reads before writing a single line of code.

Using actions.write, the Consultant records four sections to the task's action history:

Patterns to follow — existing conventions in the codebase the Builder must respect. Not general advice. Specific to what Explorer found.

Risks & warnings — what could go wrong given the current change set. A major ORM bump means query patterns may have changed. A new validation library means the existing pattern for form handling is now inconsistent. These aren't hypotheticals — they're derived from the actual diff.

Best practices — key considerations for this task given the project's current state.

Dependency notes — only when the task touches package.json. What changed, what the breaking changes are, and whether agent skill files need to be refreshed.

The Builder reads all of this via actions.get(taskId) before starting. Explorer's analysis plus Consultant's advisory gives Builder the full picture — not just what the codebase looks like, but what changed and what to watch for.

The advisory-only constraint is not an accident

The Consultant has Read and Bash access (for reading files and running safe diagnostic commands). It does not have write access. Cannot create files. Cannot modify source. Cannot touch the database.

This is intentional, and it matters.

An advisory role that can also write is a role that will, at some point, decide the advisory isn't enough and start making "small fixes" on the way to handing off. That's how you end up with an agent that's half-consultant, half-builder, and fully unclear about what it changed. The Consultant's value is precisely that it stays read-only: it can be thorough, it can be wrong, and it can be ignored — and none of those outcomes damage the codebase.

The mandatory docs criterion

The same release ships a second change that's smaller in implementation but meaningful in practice: every task now gets a mandatory acceptance criterion appended by the Lead before any work begins.

The criterion reads:

"Docs/README analysis: [describe whether docs/, README.md, or other documentation files need to reflect this change and what specifically — or explicitly state 'no update needed' with brief reasoning]"

This is the last acceptance criterion on every task, enforced by the Reviewer. If it's missing, Reviewer blocks with: "Missing mandatory docs/README analysis criterion. Lead must add it before builder proceeds." If it's present but the Builder's action summary is silent on it, Reviewer blocks with: "Docs analysis criterion is present but undocumented."

The result is explicit documentation accountability on every single task — not as a policy document, not as a guideline in a CONTRIBUTING.md nobody reads, but as a hard gate at the end of the workflow.

The updated workflow

Lead
  ↓  (always)
Explorer
  ↓  (conditional: significant dep changes or task touches package.json)
Consultant
  ↓  (always)
Builder
  ↓  (always)
Reviewer  ←  enforces docs criterion + all acceptance criteria

The chain is still Lead → Explorer → Builder → Reviewer for the majority of tasks. The Consultant enters when it earns its place. When it does, Builder gets a brief that covers not just what the codebase looks like, but what shifted and what that means.

Getting v1.6.4

npx @cardor/agent-harness-kit init

If you already have a harness in a project, sync the updated agent files:

ahk build

The consultant.md agent file will be added to .claude/agents/, .opencode/agents/, and .codex/agents/ depending on your provider config. The two new MCP tools register automatically. The mandatory docs criterion is baked into the Lead's updated instructions.

Built with agent-harness-kit — provider-agnostic scaffolding for structured multi-agent AI workflows.

One Does Not Simply read_file('/etc/passwd') — Argument Policies Land in Heimdall MCP

Enmanuel Magallanes Pinargote — Tue, 26 May 2026 13:24:16 +0000

The gap

Heimdall MCP is a transparent MCP proxy — it sits between your MCP client and any server, records every call as an OpenTelemetry span, and enforces per-server allow/deny policies without touching server code.

The policy layer in v1.3 could answer one question: can this tool be called at all? If read_file was in the allowlist, every call to read_file went through — regardless of the path argument. That's a meaningful gap. The tool name check was never the full story.

v1.4 closes it.

Website: https://stack.cardor.dev/heimdall

What shipped

A new toolPolicies field in heimdall.config.ts lets you define per-argument constraints on tools that already passed the name check. It's a separate field from tools (which stays unchanged) — so every existing config works without modification.

// heimdall.config.ts
export default {
  servers: {
    filesystem: {
      tools: { allow: ['read_file', 'list_directory'] }, // unchanged
      toolPolicies: {
        // '*' applies to all tools — merged first, tool-specific overrides on conflict
        '*': {
          args: {
            path: { isPath: true, deny_pattern: ['\\.env$', '\\.pem$'] },
          },
        },
        read_file: {
          args: {
            path: {
              isPath: true,
              allow_pattern: './',       // must resolve within cwd
              deny_pattern: ['\\.env$'], // never .env files
            },
            encoding: {
              allow_pattern: ['utf-8', 'utf8', 'ascii'],
            },
          },
        },
      },
    },
  },
} satisfies HeimdallConfig;

ArgConstraint fields

Field	Type	Default	Description
`isPath`	`boolean`	`false`	Enables path-aware matching instead of regex
`allow_pattern`	`string \	string[]`	—
`deny_pattern`	`string \	string[]`	—
`array_mode`	`'all' \	'any'`	`'all'`
`case_sensitive`	`boolean`	`true`	Regex flag; ignored for path matching
`warn_only`	`boolean`	`false`	Record violation in span without blocking

Path scoping

When isPath: true, patterns that look like directory roots are treated as containment checks rather than regex expressions:

Pattern	Meaning
`"./"` or `"."`	Arg must resolve within `process.cwd()`
`"/some/dir"`	Arg must resolve within that directory
`"~"` / `"${HOME}/projects"`	Resolved to homedir
`"${CWD}/data"`	Resolved to cwd + `/data`

The resolver uses path.resolve + fs.realpathSync on the deepest existing ancestor of the path, which handles non-existent files (e.g. pre-creation checks), ../ traversal, and symlink escapes. /tmp on macOS resolves to /private/tmp and containment is checked correctly.

Patterns that don't look like directory roots (e.g. "^/etc/.*", "\\.env$") fall back to standard regex matching.

`warn_only` mode

Useful for gradual rollout. Set warn_only: true on any constraint to observe violations without blocking:

path: { isPath: true, allow_pattern: './', warn_only: true }

The call is forwarded and these attributes appear in the OTel span:

policy.arg_warning = true
policy.arg_warning_field = "path"
policy.arg_warning_message = "Tool arg 'path' does not match the allow policy"

Switch to warn_only: false (the default) when you're ready to enforce.

Wildcard tool key and dot notation

'*' in toolPolicies applies constraints to all tools. Tool-specific entries are merged on top — specific wins on conflict, wildcard fills in fields the specific entry doesn't define.

Dot notation accesses nested argument objects:

toolPolicies: {
  my_tool: {
    args: {
      'options.target': { isPath: true, allow_pattern: './' },
    },
  },
}

Merge strategy (global + local configs)

The same security-first semantics from the tools field apply to toolPolicies when merging a global and local config:

deny_pattern: union — denied by either = denied
allow_pattern: intersection — must be in both; empty/missing defers to the other side
Structural fields (isPath, array_mode, warn_only): local wins

What Heimdall could already do (context)

For those new to the project: Heimdall MCP is a transparent proxy for any MCP server. Before v1.4 it already provided:

OpenTelemetry tracing — every tool call as an OTel span with latency breakdown, request/response hashes, and error classification. Exportable to Jaeger, Tempo, or any OTLP backend.
Persistent storage — spans saved to SQLite, PostgreSQL, or MySQL via Drizzle ORM.
Tool name policies — per-server allow/deny lists for tools, prompts, and resources. Denied calls return JSON-RPC error -32001 and never reach the server.
Body modes — full, hash, or redacted for request/response capture.
Four transport modes — stdio subprocess, HTTP, SSE, or library (embed in your own Node.js app).

v1.4 adds the argument layer on top of name-layer policies. Zero breaking changes.

Implementation notes

toolPolicies is a sibling field of tools in ServerPolicy — existing tools allow/deny lists are untouched.
Validation via valibot at startup — descriptive errors for misconfigured constraints.
PolicyInterceptor pipeline position unchanged: name check runs first, then arg check. If name is blocked, arg check is skipped.
All 192 tests pass including 43 new tests for path resolver and argument policies.

When smart is not enough — Multi-agent AI orchestration defaults

Enmanuel Magallanes Pinargote — Wed, 20 May 2026 14:00:00 +0000

Imagine a relay race where all four runners are Olympic-level athletes. Fast, technically perfect, experienced. Now imagine nobody told them the running order. The handoff protocol. Who holds the baton first.

What happens? Someone starts. Maybe the right person, maybe not. The baton gets passed in the wrong direction. Two runners reach the same point at the same time. The team is brilliant. The race is chaos.

This is the exact problem with multi-agent AI orchestration when you skip the config.

Website: https://stack.cardor.dev/ahk

The orchestration gap

The standard setup for a structured multi-agent workflow looks like this:

Lead — decomposes the task, plans, delegates
Explorer — reads and maps the codebase, never writes
Builder — implements the plan
Reviewer — verifies, approves, or blocks

Four specialized roles. Clean separation of concerns. The kind of structure that turns "fix this bug" into a systematic, auditable workflow with full history and no duplicated effort.

The problem: most setups define these roles in markdown files with descriptions like:

"Use this agent to orchestrate a full task. Invoke when starting a new work session."

That description tells the model what the lead is supposed to do. It does not tell the tool to start with lead by default. Those are two different things. And when your AI tool opens a project without an explicit default agent config, it either picks the first agent it finds alphabetically, falls back to its own built-in default, or just asks you — which defeats the point of having a structured workflow in the first place.

The relay baton is a config field, not an instruction

Here's what actually controls who goes first in each tool.

Claude Code uses the agent field in .claude/settings.json:

{
  "agent": "lead"
}

This is the official, documented field for setting which subagent runs as the main session thread. A common mistake — including one we caught in our own materializer — is putting default_agent: "lead" in .claude/mcp.json. That field doesn't exist in Claude Code's config spec. It gets ignored silently, and your session starts wherever Claude decides.

OpenCode uses default_agent in opencode.json:

{
  "default_agent": "lead",
  "compaction": { "auto": true, "prune": true, "reserved": 10000 }
}

This maps correctly. OpenCode also exposes compaction config for managing context window pressure during long orchestrated sessions — useful when lead, explorer, builder, and reviewer are all accumulating history in the same run.

Codex CLI has no direct default_agent field. Instead, Codex ships with a built-in agent named default. You override it by creating .codex/agents/default.toml with your lead agent's instructions and name = "default". Codex will use it as the entry point from that point on.

name = "default"
sandbox_mode = "read-only"

description = """
Use this agent to orchestrate a full task from the harness backlog: decompose it
into a plan, delegate to explorer, builder, and reviewer in sequence.
"""

developer_instructions = """
# Lead Agent

You are the lead agent. Your job is to orchestrate the workflow for one task at
a time. You coordinate — you do not implement.
...
"""

The second problem: roles without enforcement

Getting the starting agent right is half the battle. The other half is making sure each agent stays in its lane once the relay is running.

Instructions help. But instructions are text. A builder told "don't read source files outside src/" can still read them if nothing stops it. An explorer told "never write files" can still write if it decides that's the fastest path. One slightly off prompt, one edge case, and the contract breaks.

This is where per-role sandboxing does real work.

Claude Code exposes permissionMode as a frontmatter field on each agent .md file:

---
name: explorer
permissionMode: plan
---

plan mode puts the session into read-only planning mode — file writes and edits are blocked at the tool level. Not instruction. Enforcement.

For builder:

---
name: builder
permissionMode: acceptEdits
---

acceptEdits means file edits are auto-approved without a per-change confirmation prompt — the right tradeoff for an agent whose whole job is to implement.

Codex CLI uses sandbox_mode per agent TOML file:

# explorer.toml
name = "explorer"
sandbox_mode = "read-only"

# builder.toml
name = "builder"
sandbox_mode = "workspace-write"

The full matrix across our four roles:

Agent	Claude Code permissionMode	Codex sandbox_mode
lead	plan	read-only
explorer	plan	read-only
builder	acceptEdits	workspace-write
reviewer	plan	read-only

Why this saves tokens, not just sanity

There's an economic argument here that goes beyond correctness.

When orchestration defaults are wrong, you burn tokens at the start of every session re-establishing context. Lead has to re-introduce itself. The wrong agent hands off awkwardly. The model spends turns figuring out where it is in the workflow instead of doing the work. Then you re-prompt. Then you clarify. Then you maybe restart.

When defaults are right, the first turn is already positioned correctly. Lead picks up the task, decomposes it, passes the baton to explorer. Explorer maps the codebase, passes to builder. Builder implements, passes to reviewer. Clean chain. No re-orientation. The first session draft is the good one.

The model's intelligence is the same. The setup is what changes the output quality on the first try. More predictable behavior, fewer iterations, less token waste — not because the model got smarter, but because it didn't have to guess its starting position.

Provider comparison

Feature	Claude Code	OpenCode	Codex CLI
Agent files	`.claude/agents/*.md`	`.opencode/agents/*.md`	`.codex/agents/*.toml`
File format	Markdown + YAML frontmatter	Markdown + YAML frontmatter	TOML
Default agent field	`agent` in `settings.json`	`default_agent` in `opencode.json`	Override built-in via `default.toml`
Per-role permissions	`permissionMode` in frontmatter	— (global only)	`sandbox_mode` in TOML
MCP config file	`.claude/mcp.json`	`opencode.json`	`.codex/config.toml`
Compaction config	Not exposed	`compaction.{auto,prune,reserved}`	Not applicable

Putting it together

All of this is automated in agent-harness-kit. One command scaffolds the full structure — agents, MCP config, default agent wiring, sandbox settings — for whichever provider you choose:

npx ahk init --provider codex-cli
npx ahk init --provider claude-code
npx ahk init --provider opencode

The materializer knows which field to write to, in which file, in which format. You get correct defaults without cross-referencing three different docs pages — or discovering six months later that your default_agent key in mcp.json was doing nothing.

The relay metaphor holds

Back to the runners. The baton problem isn't about ability — it's about protocol. Define the protocol in config, not in prose. Each runner in their lane, with the right access, in the right order.

The relay runs itself. You just watch the race.

Built with agent-harness-kit — provider-agnostic scaffolding for structured multi-agent AI workflows.

You Shall Not Pass — Allow/Deny Policies for MCP Tools Are Now in Heimdall

Enmanuel Magallanes Pinargote — Tue, 19 May 2026 16:00:00 +0000

What shipped

Heimdall MCP is a transparent MCP proxy — and v1.2 adds the piece that was missing: a two-level policy config that lets you define exactly which tools, prompts, and resources each MCP server is allowed to expose to the agent.

No changes to the server. No custom middleware. A single config file next to your code.

Website: https://stack.cardor.dev/heimdall

The config: two levels, one merge

Scope	Path	Purpose
Local	`{project-root}/heimdall.config.{ts,js,json}`	Per-repo rules
Global	`~/.config/heimdall/heimdall.config.{ts,js,json}`	User/org-wide rules

Both are optional. If neither exists, Heimdall stays fully transparent — backward compatible.

When both exist, they merge with security-first semantics:

Deny → union: denied by either = denied. Global deny cannot be overridden locally.
Allow → intersection: must pass both. Wildcard * means "defer to the other side."
Deny beats allow within any single config.

This means your global config enforces a floor the team can't accidentally loosen. Local configs can only add more restrictions, never fewer.

Config format

// heimdall.config.ts
import type { HeimdallConfig } from '@cardor/heimdall-mcp';

export default {
  // default: applies to servers without an explicit entry
  default: {
    tools: { allow: ['*'], deny: [] },
  },

  // servers: keyed by --server-name flag (or serverInfo.name from initialize)
  servers: {
    filesystem: {
      tools: {
        allow: ['read_file', 'list_directory', 'search_files'],
        deny:  ['write_file', 'create_file', 'delete_file', 'move_file'],
      },
      resources: {
        allow: ['*'],
        deny:  ['file:///etc/*', 'file:///root/*'],
      },
    },
    database: {
      tools: {
        allow: ['query', 'describe_table', 'list_tables'],
        deny:  ['execute', 'drop_table', 'truncate'],
      },
    },
  },
} satisfies HeimdallConfig;

Full TypeScript with type checking. Also works as .js, .mjs, or .json.

What happens when a tool is blocked

The call never reaches the real server:

[TelemetryInterceptor] → [PolicyInterceptor] → [ForwardInterceptor]
                                ↑
                         blocks here, returns JSON-RPC error

Client receives:

{
  "jsonrpc": "2.0",
  "id": 42,
  "error": {
    "code": -32001,
    "message": "Tool 'write_file' is not permitted by policy"
  }
}

The OTel span is still recorded with policy.blocked = true, mcp.error.code = -32001, and the tool name — full audit trail of what was attempted, blocked, and when.

List responses are also filtered

tools/list, prompts/list, and resources/list responses are filtered before the client sees them — denied entries are removed. The agent doesn't even know a denied tool exists.

Server name matching

Policy entries are keyed by server name. Use --server-name to set it explicitly in your MCP config:

{
  "mcpServers": {
    "filesystem": {
      "command": "heimdall-mcp",
      "args": [
        "start",
        "--store", "sqlite://~/.heimdall/traces.db",
        "--server-name", "filesystem",
        "--",
        "npx", "@modelcontextprotocol/server-filesystem", "/home/user/projects"
      ]
    }
  }
}

--server-name overrides serverInfo.name from the initialize response — for both policy lookup and the mcp.server.name OTel attribute. Consistent everywhere.

Two new CLI commands

# Scaffold a local config with commented examples
heimdall-mcp init

# Scaffold a global config
heimdall-mcp init --global

# Validate config, show merged policy, detect allow+deny conflicts
heimdall-mcp health

health output:

Config files loaded:
  global: ~/.config/heimdall/heimdall.config.ts
  local:  ./heimdall.config.ts

Default policy:
    tools: allow=[*] deny=[none]

Server policies:
  filesystem:
      tools: allow=[read_file, list_directory, search_files] deny=[write_file, create_file, delete_file, move_file]
  database:
      tools: allow=[query, describe_table, list_tables] deny=[execute, drop_table, truncate]

No conflicts detected.

If the same name appears in both allow and deny, health exits 1 and lists all conflicts.

Library API

import { ProxyBuilder } from '@cardor/heimdall-mcp';
import type { HeimdallConfig } from '@cardor/heimdall-mcp';

const policy: HeimdallConfig = {
  servers: {
    filesystem: { tools: { deny: ['write_file', 'delete_file'] } },
  },
};

const proxy = await ProxyBuilder.create()
  .inbound({ transport: 'stdio' })
  .outbound({ transport: 'stdio', command: 'npx', args: ['@modelcontextprotocol/server-filesystem', '/tmp'] })
  .store('sqlite://./traces.db')
  .config(policy)          // attach policy
  .serverName('filesystem') // match config key
  .build();

await proxy.start();

Implementation notes

Config loaded via jiti — supports .ts, .js, .mjs, .cjs, .json without pre-compilation (same loader Vite/Nuxt use)
Schema validated by valibot at startup — descriptive errors for invalid configs
PolicyInterceptor sits between TelemetryInterceptor and ForwardInterceptor — blocked calls are recorded but never forwarded

Stop flying blind with MCP calls

Enmanuel Magallanes Pinargote — Thu, 14 May 2026 18:08:51 +0000

After getting frustrated not knowing what was actually happening inside MCP servers — which tools were slow, which failed silently, what inputs Claude was sending.

The idea: a transparent proxy that sits between your MCP client (Claude Desktop, OpenCode, Cursor) and any MCP server, captures every JSON-RPC message as an OpenTelemetry span, and persists it to a storage backend you configure.

No modifications to the target server required. You just wrap it in mcp.json:

  "command": "heimdall-mcp",
  "args": ["--store", "sqlite://~/.heimdall/traces.db", "--", "node", "my-server.js"]

For remote servers (HTTP/SSE):

  "command": "heimdall-mcp",
  "args": ["--store", "postgres://...", "--target", "http://remote-server/sse"]

Storage options: SQLite (local WASM, no native deps), Postgres, MySQL, or any OTLP-compatible backend.

Also ships as a TypeScript library with a fluent builder API if you want to embed it directly.

Why I think this is useful:

LLM agents are increasingly orchestrating MCP tools, but observability tooling hasn't caught up
IBM's ContextForge does something similar but it's a heavy Python gateway — this is meant to be a lightweight npm package

Still early (v0.1), but the core proxy + SQLite store is working. Looking for feedback on the interceptor API design and whether the OTel semantic conventions mapping makes sense.

Website: https://stack.cardor.dev/heimdall
GitHub: https://github.com/enmanuelmag/heimdall-mcp

Check the repo for more feature planned on roadmap 🚀

Heimdall MCP: Add OpenTelemetry tracing to any MCP server without touching its code

Enmanuel Magallanes Pinargote — Sat, 09 May 2026 14:03:48 +0000

If you've been building with MCP servers lately, you've probably hit this wall: something goes wrong (or just feels slow) and you have zero visibility into what actually happened.

Which tool did Claude call? What input did it send? Did the server error silently? How long did it take?

That's the gap Heimdall fills.

What is Heimdall?

Heimdall is a transparent proxy for MCP servers. It sits between your MCP client (Claude Desktop, OpenCode, Cursor, or any other) and your MCP server — local or remote — and records every interaction as an OpenTelemetry span.

No modifications to your server. No SDK to integrate. No infra to run. Just wrap your existing server and start seeing what's happening inside.

The name comes from Norse mythology: Heimdall is the guardian of the Bifrost bridge, with the ability to see and hear everything that crosses between worlds. That's exactly the role this proxy plays.

The problem in one screenshot

You're running a Claude agent that orchestrates 5+ MCP tools. One of them is consistently slow. Another occasionally returns empty results. You have no way to know which one, when, or why — unless you dig into logs manually.

With Heimdall, every tool call becomes a structured span:

{
  "name": "mcp.tool.call",
  "attributes": {
    "gen_ai.tool.name": "search_documents",
    "mcp.duration_ms": 843,
    "mcp.status": "ok"
  },
  "events": [
    { "name": "request",  "body": { "query": "quarterly report" } },
    { "name": "response", "body": { "results": [...] } }
  ]
}

Stored. Queryable. Yours.

Zero config wrapping via mcp.json

The easiest way to use Heimdall requires zero access to the server's source code. Just install it globally and update your mcp.json:

npm install -g @cardor/heimdall-mcp

Before — your current config:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["my-server.js"]
    }
  }
}

After — wrapped with Heimdall:

{
  "mcpServers": {
    "my-server": {
      "command": "heimdall",
      "args": [
        "--store", "sqlite://~/.heimdall/traces.db",
        "--",
        "node", "my-server.js"
      ]
    }
  }
}

That's it. Restart your client and every tool call starts being recorded. The -- separator tells Heimdall where its args end and the real server command begins.

For remote servers (HTTP or SSE), it's just as simple:

{
  "mcpServers": {
    "remote-server": {
      "command": "heimdall",
      "args": [
        "--store", "postgres://user:pass@localhost/mydb",
        "--target", "http://my-remote-mcp.com/sse"
      ]
    }
  }
}

Heimdall exposes stdio to your client, talks HTTP/SSE to the real server, and intercepts everything in between.

What gets recorded

Heimdall captures all standard MCP events:

Event	What's recorded
`tools/call`	Tool name, input args, response, duration, status
`tools/list`	Available tools and their schemas
`resources/read`	URI, MIME type, response size
`prompts/get`	Prompt name, arguments, rendered output
`initialize`	Client/server versions, negotiated capabilities
`shutdown`	Total session duration

Every span follows the OpenTelemetry gen_ai.* semantic conventions,
so if you later want to send traces to Jaeger, Honeycomb, or Grafana Tempo, the data is already well-formed.

Storage options

Pick the backend that fits your setup:

SQLite — local file, zero infra

--store sqlite://./traces.db
# or with absolute path
--store sqlite:///Users/you/.heimdall/traces.db

Best for: local development, single-machine setups, quick debugging sessions.

Uses @libsql/client under the hood — pure WASM, no native bindings, no node-gyp.

Postgres — your existing database

--store postgres://user:password@localhost:5432/mydb

Best for: production environments, teams sharing observability data,
long-term storage with SQL queries across multiple servers.

MySQL

--store mysql://user:password@localhost:3306/mydb

Same use case as Postgres. Pick whichever you already run.

All three use drizzle-orm with a shared schema, so the query experience is consistent regardless of which backend you choose.

Using it as a TypeScript library

If you have access to your server's code and want tighter integration, Heimdall ships as a fully-typed TypeScript library with a fluent builder API:

import { McpProxy } from 'heimdall-mcp'

const proxy = await McpProxy
  .create()
  .inbound({ transport: 'stdio' })
  .outbound({ transport: 'http', url: 'http://localhost:3001' })
  .store('sqlite://./traces.db')
  .build()

await proxy.start()

You can also plug in custom interceptors — for example, to redact sensitive fields before they're persisted, or to add your own business logic on top of the tracing:

import { McpProxy, type Interceptor } from 'heimdall-mcp'

// Custom interceptor: redact API keys from tool inputs before storing
const redactSecrets: Interceptor = {
  name: 'redact-secrets',
  async intercept(request, ctx, next) {
    const sanitized = redactSensitiveFields(request)
    return next(sanitized)
  }
}

const proxy = await McpProxy
  .create()
  .inbound({ transport: 'stdio' })
  .outbound({ transport: 'http', url: 'http://localhost:3001' })
  .store('postgres://user:pass@host/db')
  .intercept(redactSecrets)
  .build()

Design goals

A few decisions worth calling out:

No native dependencies. SQLite runs via WASM (@libsql/client), Postgres via the pure-JS postgres package, MySQL via mysql2. You can install and run Heimdall in any Node 22+ environment without compilation steps.

No policy opinions. Heimdall doesn't block, approve, or modify tool calls. It only observes and records. If you need access control or rate limiting, pair it with a tool like mcpwall.

Transport mixing. Your client connects via stdio. Your server can be stdio, HTTP, or SSE. Heimdall bridges them transparently — useful for wrapping local CLI servers behind an HTTP interface without touching their code.

Get started

npm install -g @cardor/heimdall-mcp

GitHub: github.com/enmanuelmag/heimdall-mcp
Website: https://heimdall-mcp.cardor.dev

If you try it out, I'd love to hear what you think — especially feedback on the interceptor API design and the OTel schema. Open an issue or find me on X [@enmanuelmag].

I got tired of AI agents roaming my codebase — so I built a harness layer

Enmanuel Magallanes Pinargote — Wed, 06 May 2026 00:55:08 +0000

The problem

Every time I open Claude Code or any MCP-compatible AI tool, the same thing happens: the agent starts working, does something, and I have no idea what it changed, what it tried, or why it got stuck. Across sessions, it's even worse — the agent has no memory of what was already attempted.

If you want multiple agents working in parallel or in sequence, good luck coordinating them without race conditions, double work, or conflicting changes.

I wanted something I could actually trust to run on my codebase.

What I built

agent-harness-kit (ahk) is a scaffolding layer for structured multi-agent workflows. One command drops it into any project:

npx ahk init

t creates a local MCP server (runs on stdio, no ports needed), a SQLite database, a task backlog, a health gate, and four agent definition files.

How it works

The 4-agent workflow

Lead → Explorer → Builder → Reviewer

Lead decomposes the task into a plan. Never reads source files.
Explorer maps the codebase. Never writes files.
Builder implements. Only writes to writablePaths you define.
Reviewer checks acceptance criteria. Runs health check before approving.

Each role has its own Markdown file you can customize. They're created once and never overwritten.

Atomic task claiming

tasks.claim(id, agent)  // SQLite transaction — no double-work possible

Two agents can't grab the same task. The second one gets task_already_claimed and moves on.

Health gate

Before any agent starts or closes a task, it runs your health.sh:

#!/usr/bin/env bash
npm test || exit 1
curl -sf http://localhost:3000/health > /dev/null || exit 1
echo "All checks passed."

If it exits with anything other than 0, the task stays open. You define what "healthy" means for your project.

Full audit trail

Every action is recorded:

actions.start(taskId, agent)             // start
actions.write(actionId, 'files_modified', 'src/auth.ts, src/routes/login.ts')
actions.write(actionId, 'result', '...')
actions.complete(actionId, 'summary')    // close

ahk export --json dumps the full history.

Provider-agnostic

Works with Claude Code today. Moving to OpenCode? One command:

ahk migrate --to opencode

Your task history, agent definitions, and config stay intact.

No cloud, no native deps

Everything lives in .harness/harness.db (SQLite, gitignored). Uses node:sqlite built-in — no node-gyp, no native compilation.

Requirements: Node ≥ 22 or Bun.

Get started

npx ahk init

Interactive setup. Asks for your project name, AI provider, docs path, and an optional first task. Creates everything in under a minute.

GitHub: github.com/enmanuelmag/agent-harness-kit
npm: @cardor/agent-harness-kit

I'd love feedback on the health gate design and the atomic claiming approach — those were the trickiest parts to get right.

Security Logger

Enmanuel Magallanes Pinargote — Tue, 16 Jan 2024 13:56:10 +0000

Disclaimer: The only real data in this site was hidden to protect the privacy of the user. The rest of the data is fake.

This project is build with ViteJs and ReactJs, the main idea is to create a web app and also a native desktop app to register new visitors on urbanization, the web app is for the directive (i.e urbanization president) and the desktop app is for the security guard.

The app allow to create user three types of user:

Admin: Can create new users and also can see all the logs
Security guard: Can create, read and update new logs
Guest: Can only read the logs

The records are stored first in the IndexDB and then are synced with the Firestore database, the app also has a offline mode, so the user can use the app without internet connection and when the connection is available the app will sync the data with the database.

The records could be filtered by visitor name, visitor ID, date, and also by the house number, the app also has a search bar that allow to search by name quickly. Also, you can exported the entire records of filtered records to a XLSX file or a PDF file.

Deep learning integration

This app also has a integration with a other personal project, that consist in a Deep Learning model that can detect and extract the text of visitor name and ID from a image. So the app can extract the image from the security camera that focus the visitor ID and the model will extract the text and fill the form with the data. The information can be edited by the security guard too. The model is build with Tensorflow based on a little version of YOLOv5.

Currently the app is only available in Spanish, and deploy or installation is only available previos contact and agreement. The app will have more tools powered by AI to detect and extract more information as vehicle plate, visitor face, etc.

Tech used

Firebase (Auth, Firestore)
ReactJs, React Router, React Context
React-Query
Zod (Validation)
Tensorflow

Budgetfy

Enmanuel Magallanes Pinargote — Tue, 16 Jan 2024 13:50:59 +0000

In this web app you can create budget to define your expenses and incomes as unique events or recurrent events as you usually create events for a calendar, in order to plan your budget through slice of time that you can define.

The Budget view has show you one card per moth with three sections. The first section is Category summary, it show the total amount of money for each category that you have defined.

The second section is Timeline, that show the following information:

Timeline: show all the events for that month (expenses and incomes) and the estimated balance for that month. Also if you clic on the event you can mark it as paid (for expenses) or received (for incomes). This will update the balance.
Balance: section you will see all the money available without expenses for that month and the monthly balance, it mean the difference between the incomes and the expenses for that specific month.

Finally the third section is the Timeline plot, that show the evolution of the incomes, expenses and balance for the the defined range of time on the budget creation.

You can create a account for free using a email and password or Google account, then you can create your budget and start to add your incomes and expenses. Visit the website to see more details.

Tech used

Firebase (Auth, Firestore)
ReactJs, React Router, React Context
React-Query
Highcharts
Zod (Validation)

IAflow

Enmanuel Magallanes Pinargote — Tue, 16 Jan 2024 13:42:19 +0000

This library help to create models with identifiers, checkpoints, logs and metadata automatically, in order to make the training process more efficient and traceable.

For install the library, you can use pip:

pip install iaflow

Then you can create the ia_make with the following code:

ia_maker = IAFlow(
  models_folder='./models',
  checkpoint_params={
    'monitor': 'val_loss',
    'save_best_only': True,
    'save_weights_only': True
  },
  tensorboard_params={
    'histogram_freq': 1,
    'write_graph': True,
    'write_images': True
  }
)

And then you can add the model with the following code:

model_1_data = ia_maker.add_model(
  model_name='model_1',
  model_params={ 'input_shape': (2, 1) },
  load_model_params={},
  compile_params={
    'metrics': ['accuracy'],
    'optimizer': 'adam', 'loss': 'mse'
  },
)

Finally, you can train the model with the following code:

ia_maker.train(
  model_1_data,
  epochs=5,
  dataset_name='dataset_1'
)

This library has integration with Notifier Status Function, so you can send notifications to Telegram when the training process is finished. To check how to use it and more feature as managing Dataset and Models with the library, you can check the documentation.

Tech used

Python
Tensorflow
Telegram API
Notifier Status Function (personal lib)
Webhooks

Mi Horario Web (MHW)

Enmanuel Magallanes Pinargote — Tue, 16 Jan 2024 13:39:51 +0000

Disclaimer: Currently we are working on improve and update of NodeJS version of the Lambda functions, so the website is not working properly.

This is an online timetable generator for students of the ESPOL University. It allows to obtain information of the planned courses, statistics of the teacher in charge and to generate options of schedules according to the courses and selected parallels.

The project is developed in React and Material-UI, MongoDB as main database for all courses information and FireStore as realtime database for update de progress of schedule generation on the client side.

The steps to create schedules are:

Select the subjects that you will take.
Selected the course numbers that you would like to choose. In this section you can also see the course's teacher, his/her qualification and student's opinios about him/her.
The you can execute the schedules generations, the process can take a while, so a progress bar is show up with the progress update in real time.
Finally you can see all the options of schedules with out conflict on hours class or exams. You can also download the information as a table (just course numbers and subject) or download the calendar view.

Tech used

React
Material-UI
MongoDB
Highcharts
AWS State Machine
AWS Lambda Functions
Firebase (Auth, Firestore)
Github Actions

Notifier Function Status

Enmanuel Magallanes Pinargote — Tue, 16 Jan 2024 13:34:38 +0000

This library provides a decorator to show a toast in your screen and if you setup, send a email when your function end. All that you need to do is use a decorator and some specific parameters, like in the following example:

from notifier import notify

# Send a message to telegram
@notify(api_token='your_api_token', chat_id='your_chat_id')
def your_function():
    print('Hello World!')

Another way is by manually calling the function:

from notifier import Notifier

notifier = Notifier(
  title='Execution for',
  api_token='your_api_token'
  chat_id='your_chat_id'
)

for i in range(10):
    notifier(msg=f'Hello World {i}!')

# You can also override all the previous parameters,
# on the constructor, by passing them to the function
notifier(title='Execution done', msg='Finished!')

Check these features a more detailed on the GitHub repository.

Tech used

Python
Telegram API
Discord webhooks

DEV Community: Enmanuel Magallanes Pinargote

The Map Is Not the Territory — Dep-Aware Agent Between Explorer and Builder

The intelligence problem

Your Explorer's map goes stale

A fifth role for a specific problem

The MCP tools that make it work

What the Consultant actually produces

The advisory-only constraint is not an accident

The mandatory docs criterion

The updated workflow

Getting v1.6.4

One Does Not Simply read_file('/etc/passwd') — Argument Policies Land in Heimdall MCP

The gap

What shipped

ArgConstraint fields

Path scoping

warn_only mode

Wildcard tool key and dot notation

Merge strategy (global + local configs)

What Heimdall could already do (context)

Implementation notes

Links

When smart is not enough — Multi-agent AI orchestration defaults

The orchestration gap

The relay baton is a config field, not an instruction

The second problem: roles without enforcement

Why this saves tokens, not just sanity

Provider comparison

Putting it together

The relay metaphor holds

You Shall Not Pass — Allow/Deny Policies for MCP Tools Are Now in Heimdall

What shipped

The config: two levels, one merge

Config format

What happens when a tool is blocked

List responses are also filtered

Server name matching

Two new CLI commands

Library API

Implementation notes

Links

Stop flying blind with MCP calls

Heimdall MCP: Add OpenTelemetry tracing to any MCP server without touching its code

What is Heimdall?

The problem in one screenshot

Zero config wrapping via mcp.json

What gets recorded

Storage options

SQLite — local file, zero infra

Postgres — your existing database

MySQL

Using it as a TypeScript library

Design goals

Get started

I got tired of AI agents roaming my codebase — so I built a harness layer

The problem

What I built

How it works

The 4-agent workflow

Atomic task claiming

Health gate

Full audit trail

Provider-agnostic

No cloud, no native deps

Get started

Security Logger

Deep learning integration

Tech used

Budgetfy

Tech used

IAflow

Tech used

Mi Horario Web (MHW)

Tech used

Notifier Function Status

Tech used

`warn_only` mode