diff --git a/README.md b/README.md index 7d6778e4..12af7965 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,39 @@ # 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 — 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) [![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'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. + +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. + +## 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 -- [Overview](#overview) +- [The Personality](#the-personality) +- [Why Madz](#why-madz) +- [Use Cases](#use-cases) +- [How It Works](#how-it-works) - [Quick Start](#quick-start) - [Prerequisites](#prerequisites) - [Installation](#installation) @@ -29,13 +52,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 +67,59 @@ - [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. +- **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. +- **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. -- 🧠 **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 +## 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. 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. + +## 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 +146,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 +631,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.