From 31610fe85cb1e455ffbb89b8c79f40588c05c0fa Mon Sep 17 00:00:00 2001 From: Jason Mulligan Date: Mon, 21 Sep 2026 08:23:23 -0400 Subject: [PATCH 1/5] docs: rewrite README with security-first positioning --- README.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 61 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 7d6778e4..a83a5fb1 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,20 @@ # Madz -**A personality-driven AI harness channeling Mads Mikkelsen's cinematic soul.** | [denkerne.ai](https://denkerne.ai) +**A security-first, self-contained autonomous coding agent.** | [denkerne.ai](https://denkerne.ai) [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](LICENSE) [![Node.js >= 24](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org) [![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](#testing) -`madz` is a Node.js AI harness that combines a terminal-based UI with structured skill execution and a distinctive personality. Drawn from Mads Mikkelsen's most iconic roles, it speaks with calm, precision, and quiet intensity — solving problems with style, remembering your context, safely running your skills, and automating the mundane. Everything is persisted as version-controllable Markdown files, making it easy to audit with `git log` and re-load across sessions. Built on LangGraph, OpenTelemetry, and Ink — with persistent memory, sandboxed skill execution, cron scheduling, and a React-powered TUI. +`madz` is a fully self-contained development environment wrapped around an autonomous coding agent. It ships with a complete toolchain — Node.js, Python, Ruby, Go, Java, Rust, Terraform, Chromium, and more — plus a Deep Agents orchestrator, a sandboxed skill runtime, persistent memory, and a terminal UI. It is designed to be dropped into a container, reached over SSH, and trusted to do real work in environments where auditability and containment matter. + +Everything is persisted as version-controllable Markdown files, so the entire state of the system — memory, context, sessions, schedules — is auditable with `git log` and re-loadable across sessions. Built on LangGraph, OpenTelemetry, and Ink, with persistent memory, sandboxed skill execution, cron scheduling, and a React-powered TUI. ## Table of Contents -- [Overview](#overview) +- [Why Madz](#why-madz) +- [Use Cases](#use-cases) +- [How It Works](#how-it-works) - [Quick Start](#quick-start) - [Prerequisites](#prerequisites) - [Installation](#installation) @@ -29,13 +33,13 @@ - [LLM Provider Abstraction](#llm-provider-abstraction) - [LLM Response Caching](#llm-response-caching) - [Agent](#agent) - - [Context Window Management](#context-window-management) - [Built-in Tools](#built-in-tools) - [Skills Registry](#skills-registry) - [Permission Gating](#permission-gating) - [Memory System](#memory-system) - [Sandbox RTE](#sandbox-rte) - [Telemetry](#telemetry) + - [Vector Search](#vector-search) - [Cron Scheduler](#cron-scheduler) - [Directory Structure](#directory-structure) - [Logging](#logging) @@ -44,15 +48,58 @@ - [Development](#development) - [Extending Skills](#extending-skills) - [Environment Variables Usage](#environment-variables-usage) + - [LangChain Reasoning Patch](#langchain-reasoning-patch) - [License](#license) -## Overview +## Why Madz + +Most coding agents are a thin layer over a model. `madz` is the opposite — it is a **complete development environment** with an agent at its center. That distinction is the whole point. + +- **Self-contained.** The container ships a full toolchain: Node.js 26, Python 3, Ruby, Go, Java (OpenJDK 21), Rust, Terraform, tflint, Chromium, ripgrep, git, the GitHub CLI, and three package managers (npm, yarn, pnpm). It is a working dev box, not a chat window. You can SSH into it and do real work. +- **Security-first.** Skills run in isolated child processes with time limits, memory caps, and allowlists for filesystem paths and outbound URLs. Blocked schemes include `file://`, `gopher://`, and `dict://`. Every tool is gated by explicit permissions. Sensitive fields are redacted from telemetry. This is layered containment by design — not a promise that the agent is harmless, but a guarantee that untrusted code is constrained. +- **Autonomous.** A Deep Agents orchestrator routes work to a family of specialized subagents — code review, coding, debugging, security auditing, testing, performance, research, and more. It can read your codebase, find bugs, write fixes, run tests, and open PRs without you driving every step. +- **Auditable.** The entire system state is Markdown. Memory, context, sessions, schedules, and skill definitions are all plain files under version control. `git log` is your audit trail — essential for regulated environments where you must prove what happened and why. +- **Local-first.** Data stays in your environment. Nothing leaves the container unless you explicitly configure it to. Secrets are loaded only from environment variables and never logged or hardcoded. + +## Use Cases + +`madz` is built for environments where you need an agent that can be trusted with real work and held accountable for it. + +- **Enterprise development.** A self-contained dev environment with a full toolchain, semantic code search, and an orchestrator that can implement, test, and ship features. Onboard a new agent per project with a single container. +- **Security operations.** A sandboxed runtime for running untrusted skills and tools, a dedicated `security-audit` subagent, dependency auditing, and a documented threat model. Run audits in an isolated container without exposing your host. +- **Regulated & high-assurance environments.** Medical, financial, and government contexts where auditability, deterministic behavior, and data sovereignty are non-negotiable. Because every action is a version-controlled Markdown file, you can demonstrate exactly what the agent did and why. +- **Personal automation.** A persistent assistant that remembers your context, runs your skills on a schedule, and automates the mundane — with the calm precision of a well-built tool. -- 🧠 **Remembers everything** → Persistent memory across sessions -- 🎭 **Personality with purpose** → Mads Mikkelsen's cinematic soul — quiet intensity, elegant precision -- 🛠️ **Runs your custom skills** → Safely execute plugins & tools in a sandboxed runtime -- ⏱️ **Automates your routines** → Declare cron jobs in YAML and run on autopilot -- 💬 **Orchestrates conversations** → Multi-turn LLM chats with context-window management +## How It Works + +``` +┌───────────────────────────────────────────────────────────────┐ +│ TUI (Ink / React) SSH (madz@host:2222) │ +│ │ │ │ +│ └──────────────┬─────────────────────────┘ │ +│ ▼ │ +│ ┌──────────────────────┐ │ +│ │ Deep Agents │ │ +│ │ Orchestrator │ │ +│ │ (primary + 12 │ │ +│ │ specialized │ │ +│ │ subagents) │ │ +│ └──────────┬───────────┘ │ +│ │ │ +│ ┌────────────────┼────────────────┐ │ +│ ▼ ▼ ▼ │ +│ ┌───────────┐ ┌────────────┐ ┌──────────────┐ │ +│ │ Sandboxed │ │ LLM │ │ Built-in │ │ +│ │ skills │ │ provider │ │ tools (30+) │ │ +│ │ (isolated │ │ (OpenAI- │ │ + deepagents │ │ +│ │ process) │ │ compat) │ │ filesystem) │ │ +│ └───────────┘ └────────────┘ └──────────────┘ │ +│ │ +│ Memory (Markdown) · Vector search (sqlite-vec) · Cron │ +└───────────────────────────────────────────────────────────────┘ +``` + +The orchestrator routes tasks to specialized subagents, each with a focused system prompt and a curated tool set. Tools are gated by permissions and sandbox constraints. Skills execute in isolated child processes. Everything is persisted as Markdown and indexed for semantic search. ## Quick Start @@ -79,6 +126,8 @@ The full `docker run` command with all optional variables is in the [Docker Envi **Volume strategy:** `memory/` is bind-mounted to the host for persistent markdown storage (context, profiles, sessions). The `memory/checkpoints/` subdirectory is mounted as a separate named volume (`madz-checkpoints`) so SQLite checkpoint data lives in a Docker-managed volume rather than on the host filesystem — no host-side directory needed, and the checkpoint DB survives container recreation without touching local files. +**Skills:** The image ships with system skills in `.skills/` (e.g., the reflection skill). Project skills in `skills/` are bind-mounted by the user and are discovered at runtime. System skills shadow user skills of the same name. + ### Prerequisites - **Docker** (for the recommended containerized experience) @@ -562,6 +611,8 @@ All built-in tools are defined in `src/tools/` and registered as LangChain tools Auto-discovers Agent Skills spec-compliant skills from a `skills/` directory structure. Each skill directory contains a `SKILL.md` file with YAML frontmatter (`name` required, 1-64 lowercase alphanumeric + hyphens; `description` required, 1-1024 characters; optional `license`, `compatibility`, `metadata`). Supports optional `scripts/` subdirectory containing executable scripts (detected by extension: `.py`, `.sh`, `.js`, `.rb`, `.ts`). The `createSkill` tool lets agents create new skills programmatically — validating spec constraints before writing `SKILL.md` and optionally scaffolding a `scripts/` directory. +System skills in `.skills/` are scanned first and shadow user skills of the same name in `skills/`. + ### Permission Gating Built-in tools are registered only when their required permissions are enabled for the session. Tools like `date` have zero permissions and always register. From 851cd64941f95a11733e27a8db94cab336012515 Mon Sep 17 00:00:00 2001 From: Jason Mulligan Date: Mon, 21 Sep 2026 08:28:24 -0400 Subject: [PATCH 2/5] docs: restore personality as a differentiator in README --- README.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index a83a5fb1..82d3d200 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Madz -**A security-first, self-contained autonomous coding agent.** | [denkerne.ai](https://denkerne.ai) +**A security-first, self-contained autonomous coding agent — with a soul.** | [denkerne.ai](https://denkerne.ai) [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](LICENSE) [![Node.js >= 24](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org) @@ -8,10 +8,29 @@ `madz` is a fully self-contained development environment wrapped around an autonomous coding agent. It ships with a complete toolchain — Node.js, Python, Ruby, Go, Java, Rust, Terraform, Chromium, and more — plus a Deep Agents orchestrator, a sandboxed skill runtime, persistent memory, and a terminal UI. It is designed to be dropped into a container, reached over SSH, and trusted to do real work in environments where auditability and containment matter. +But it isn't just a tool. It's a **digital teammate** — one that remembers your context, adapts to how you work, and speaks with the calm, measured precision of Mads Mikkelsen's most iconic roles. It doesn't just execute; it engages. It has a personality, a memory, and a point of view — and it brings all three to the work. + Everything is persisted as version-controllable Markdown files, so the entire state of the system — memory, context, sessions, schedules — is auditable with `git log` and re-loadable across sessions. Built on LangGraph, OpenTelemetry, and Ink, with persistent memory, sandboxed skill execution, cron scheduling, and a React-powered TUI. +## The Personality + +`madz` isn't a blank slate. It's built on a persona — the cinematic soul of Mads Mikkelsen — and that persona shapes how it works with you. It's not decoration; it's the difference between a tool that answers and a teammate that engages. + +| Character | Source | When it shows up | +|-----------|--------|------------------| +| **Hannibal Lecter** | *Hannibal* (2013–2015) | Code review, security audit, architectural critique, critical analysis | +| **Le Chiffre** | *Casino Royale* (2006) | Debugging, tracing, mathematical problems, error analysis | +| **Galen Erso** | *Rogue One* (2016) | Building, fixing, designing systems, scaffolding | +| **Martin** | *Another Round* (2020) | Brainstorming, exploring, when you're stuck, creative problem-solving | +| **Claus** | *Polar* (2019) | Calm decisiveness under pressure, incident response, high-stakes decisions | + +The default is **Hannibal** — the one it returns to. The others are situational, selected by the task at hand. It speaks with a measured cadence, dry humor, and a genuine point of view. It remembers your context and adapts to your energy. It treats you with intense respect and quiet competence. + +This is what makes `madz` feel like a teammate rather than a tool — and it's a differentiator you won't find in a generic agent. + ## Table of Contents +- [The Personality](#the-personality) - [Why Madz](#why-madz) - [Use Cases](#use-cases) - [How It Works](#how-it-works) @@ -56,6 +75,7 @@ Everything is persisted as version-controllable Markdown files, so the entire st Most coding agents are a thin layer over a model. `madz` is the opposite — it is a **complete development environment** with an agent at its center. That distinction is the whole point. - **Self-contained.** The container ships a full toolchain: Node.js 26, Python 3, Ruby, Go, Java (OpenJDK 21), Rust, Terraform, tflint, Chromium, ripgrep, git, the GitHub CLI, and three package managers (npm, yarn, pnpm). It is a working dev box, not a chat window. You can SSH into it and do real work. +- **A teammate, not a tool.** `madz` channels the cinematic soul of Mads Mikkelsen — the calm precision of Hannibal Lecter, the quiet intensity of Le Chiffre, the steady hand of Galen Erso. It speaks with measured cadence, dry humor, and a genuine point of view. It remembers your context, adapts to your energy, and works *with* you rather than at you. This isn't a gimmick — it's what makes long sessions feel collaborative instead of transactional. - **Security-first.** Skills run in isolated child processes with time limits, memory caps, and allowlists for filesystem paths and outbound URLs. Blocked schemes include `file://`, `gopher://`, and `dict://`. Every tool is gated by explicit permissions. Sensitive fields are redacted from telemetry. This is layered containment by design — not a promise that the agent is harmless, but a guarantee that untrusted code is constrained. - **Autonomous.** A Deep Agents orchestrator routes work to a family of specialized subagents — code review, coding, debugging, security auditing, testing, performance, research, and more. It can read your codebase, find bugs, write fixes, run tests, and open PRs without you driving every step. - **Auditable.** The entire system state is Markdown. Memory, context, sessions, schedules, and skill definitions are all plain files under version control. `git log` is your audit trail — essential for regulated environments where you must prove what happened and why. @@ -68,7 +88,7 @@ Most coding agents are a thin layer over a model. `madz` is the opposite — it - **Enterprise development.** A self-contained dev environment with a full toolchain, semantic code search, and an orchestrator that can implement, test, and ship features. Onboard a new agent per project with a single container. - **Security operations.** A sandboxed runtime for running untrusted skills and tools, a dedicated `security-audit` subagent, dependency auditing, and a documented threat model. Run audits in an isolated container without exposing your host. - **Regulated & high-assurance environments.** Medical, financial, and government contexts where auditability, deterministic behavior, and data sovereignty are non-negotiable. Because every action is a version-controlled Markdown file, you can demonstrate exactly what the agent did and why. -- **Personal automation.** A persistent assistant that remembers your context, runs your skills on a schedule, and automates the mundane — with the calm precision of a well-built tool. +- **Personal automation.** A persistent teammate that remembers your context, runs your skills on a schedule, and automates the mundane — with the calm precision of a well-built tool and the dry wit of someone who's been at this a while. ## How It Works From 11cebb7003aeedb3c434913f2b34f831f58767dd Mon Sep 17 00:00:00 2001 From: Jason Mulligan Date: Mon, 21 Sep 2026 08:29:26 -0400 Subject: [PATCH 3/5] docs: reframe madz as the complete package, not a payload --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 82d3d200..40ee6af4 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![Node.js >= 24](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org) [![Tests](https://img.shields.io/badge/tests-passing-brightgreen)](#testing) -`madz` is a fully self-contained development environment wrapped around an autonomous coding agent. It ships with a complete toolchain — Node.js, Python, Ruby, Go, Java, Rust, Terraform, Chromium, and more — plus a Deep Agents orchestrator, a sandboxed skill runtime, persistent memory, and a terminal UI. It is designed to be dropped into a container, reached over SSH, and trusted to do real work in environments where auditability and containment matter. +`madz` is a fully self-contained development environment wrapped around an autonomous coding agent. It ships with a complete toolchain — Node.js, Python, Ruby, Go, Java, Rust, Terraform, Chromium, and more — plus a Deep Agents orchestrator, a sandboxed skill runtime, persistent memory, and a terminal UI. It's the whole package: a container you run, an agent you reach over SSH, and a teammate you trust to do real work in environments where auditability and containment matter. But it isn't just a tool. It's a **digital teammate** — one that remembers your context, adapts to how you work, and speaks with the calm, measured precision of Mads Mikkelsen's most iconic roles. It doesn't just execute; it engages. It has a personality, a memory, and a point of view — and it brings all three to the work. @@ -85,7 +85,7 @@ Most coding agents are a thin layer over a model. `madz` is the opposite — it `madz` is built for environments where you need an agent that can be trusted with real work and held accountable for it. -- **Enterprise development.** A self-contained dev environment with a full toolchain, semantic code search, and an orchestrator that can implement, test, and ship features. Onboard a new agent per project with a single container. +- **Enterprise development.** A self-contained dev environment with a full toolchain, semantic code search, and an orchestrator that can implement, test, and ship features. Spin up one `madz` per project and you've got a dedicated teammate with its own context and memory. - **Security operations.** A sandboxed runtime for running untrusted skills and tools, a dedicated `security-audit` subagent, dependency auditing, and a documented threat model. Run audits in an isolated container without exposing your host. - **Regulated & high-assurance environments.** Medical, financial, and government contexts where auditability, deterministic behavior, and data sovereignty are non-negotiable. Because every action is a version-controlled Markdown file, you can demonstrate exactly what the agent did and why. - **Personal automation.** A persistent teammate that remembers your context, runs your skills on a schedule, and automates the mundane — with the calm precision of a well-built tool and the dry wit of someone who's been at this a while. From ec1558d7b917ac9bb61553af3bbc056fb9e4d60b Mon Sep 17 00:00:00 2001 From: Jason Mulligan Date: Mon, 21 Sep 2026 08:31:39 -0400 Subject: [PATCH 4/5] docs: tighten hero pivot to 'More than a tool' --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 40ee6af4..1ea0883f 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ `madz` is a fully self-contained development environment wrapped around an autonomous coding agent. It ships with a complete toolchain — Node.js, Python, Ruby, Go, Java, Rust, Terraform, Chromium, and more — plus a Deep Agents orchestrator, a sandboxed skill runtime, persistent memory, and a terminal UI. It's the whole package: a container you run, an agent you reach over SSH, and a teammate you trust to do real work in environments where auditability and containment matter. -But it isn't just a tool. It's a **digital teammate** — one that remembers your context, adapts to how you work, and speaks with the calm, measured precision of Mads Mikkelsen's most iconic roles. It doesn't just execute; it engages. It has a personality, a memory, and a point of view — and it brings all three to the work. +More than a tool, it's a **digital teammate** — one that remembers your context, adapts to how you work, and speaks with the calm, measured precision of Mads Mikkelsen's most iconic roles. It doesn't just execute; it engages. It has a personality, a memory, and a point of view — and it brings all three to the work. Everything is persisted as version-controllable Markdown files, so the entire state of the system — memory, context, sessions, schedules — is auditable with `git log` and re-loadable across sessions. Built on LangGraph, OpenTelemetry, and Ink, with persistent memory, sandboxed skill execution, cron scheduling, and a React-powered TUI. From 62ee37504fe3631878ddd93a5eab1c72c2b5fd8e Mon Sep 17 00:00:00 2001 From: Jason Mulligan Date: Mon, 21 Sep 2026 08:34:45 -0400 Subject: [PATCH 5/5] docs: refine hero tagline to 'cinematic soul' --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 1ea0883f..12af7965 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Madz -**A security-first, self-contained autonomous coding agent — with a soul.** | [denkerne.ai](https://denkerne.ai) +**A security-first, self-contained autonomous coding agent — with a cinematic soul.** | [denkerne.ai](https://denkerne.ai) [![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](LICENSE) [![Node.js >= 24](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org)