mcp server

HEAV3NS

HEAV3NS is a signal-first AI coding companion for VS Code and the terminal—built for clear execution, explicit approvals, and calm control over complex engineering work.

CardSorting/HEAV3NScommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

Node.js 20 or newer

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "heav3ns": {
      "command": "npx",
      "args": [
        "-y",
        "heav3ns"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 25, 2026

⚡ HEAV3NS

Your cockpit for the tight coding loop

A local-first CLI coding agent for focused, reviewable work.

Quick Links	Guides & Manuals	Deep Dives & Architecture
🚀 Quick Start	🔮 Custom Assistants (SOULs & Skills)	📐 Visual Architecture Maps
🎯 Everyday Benefits	❓ Frequently Asked Questions	🏗️ Runtime Architecture Guide
👤 Pick an AI Specialist	⌨️ Terminal & Commands Guide	🔍 Smart Search Engine (ADR-136)
📋 What's New	📖 Author's Story & Note	⚡ Cost-Saving Memory (ADR-135)
🧪 78-Test Verification Suite	📈 Live Benchmark Measurements	🏛️ Architecture Decision Records
🛩️ Agent Flight Test	📊 Benchmark Methodology	🚀 Launch & Trust Strategy
🧾 Claims & Evidence	🛡️ Security Policy	⚖️ Licensing Strategy
🤖 Claude Subscription DirectSDK Provider	Rolling QoL Roadmap	QoL Audit & Walkthrough

Dedicated to the open-source community and the creators at Nous Research & Hermes. Made with love so anyone can build with fast, reliable AI. — William Andrew Cruz (bozoegg / CardSorting) · Read Author's Note

Precision at speed. Pilot in command.

Every agent has a flight profile. Cargo planes carry the operation; fighter jets are built for tight turns. HEAV3NS takes the fighter-jet mission: one focused coding task close to the code—inspect context, make a scoped change, verify it, then hand control back to the developer. The metaphor describes our intended use, not a ranking of other agents.

“Break the sound barrier” is our north star for a shorter path from intent to evidence. It is not a measured speed claim. The Agent Flight Test checks selected harness behavior with a deterministic local provider; it does not measure live-model coding ability.

Start with the no-key harness check:

npm run benchmark:flight

Read the test protocol or the adoption and trust plan.

🌟 Why Developers Love It

What You Get	Why It Helps You Every Day	How Fast & Simple It Is
⚡ Local-first workflows	Keeps selected orchestration and review paths close to the editor; provider and network time remain visible as separate costs.	Measure with the live baseline
🔍 Project-aware search	Finds files and symbols using the workspace's configured search and perception tools.	Workspace-dependent
⏪ Reviewable recovery	Checkpoints, previews, and rollback paths help inspect changes before committing them.	External effects are out of scope
💸 Cost-aware context	Tracks context and cache behavior so users can reason about provider usage.	No savings promise
🛡️ Guarded tools	Permission and safety layers can inspect commands, paths, and tool requests before execution.	Policy- and host-dependent
🚀 Observable runtime	Health checks, tests, telemetry, and failure states make behavior easier to inspect.	Not a reliability warranty

🚀 Quick Start

# 1. Download & Build
git clone https://github.com/CardSorting/LUMI-JOY.git && cd LUMI-JOY
npm install && npm run build

# 2. Add your AI API key (friendly step-by-step wizard)
npx tsx src/index.ts --setup

# 3. Start coding!
npx tsx src/index.ts --profile coder

╔══════════════════════════════════════════════════════════════════════════════════════════╗
║ ⚡ HEAV3NS │ 👤 [💻 Coder] │ 🧠 [configured model] │ ⏱️ local measurement │ 💰 provider usage ║
╠══════════════════════════════════════════════════════════════════════════════════════════╣
║  👤 You: Refactor auth.ts to add expiration checks                                        ║
║  ⚡ HEAV3NS (Coder): Checked auth.ts and applied reviewable edits with unit tests         ║
╠══════════════════════════════════════════════════════════════════════════════════════════╣
║ 💡 Shortcuts: [Ctrl+M] Switch Model  [Ctrl+P] Setup  [/profile] Change Role  [Ctrl+C] Quit ║
╚══════════════════════════════════════════════════════════════════════════════════════════╝

Verify the CLI path

npm test runs the CLI-native Mocha unit profile in .mocharc.cli.json, then the no-key Agent Flight Test. It keeps host/editor compatibility checks out of the default feedback loop while preserving them as an explicit npm run test:legacy-host profile.

🎯 What You Get (Everyday Superpowers)

The Common Problem	How HEAV3NS Solves It	Your Real-World Benefit
Accidental bad edits or AI mistakes	Reviewable Recovery	Inspect diffs and use supported checkpoints or rollback paths; external effects may remain.
Fear of AI breaking working code	Safe Preview Sandbox	Look over proposed edits visually before anything is saved to your computer.
Searches slowing on big projects	Workspace-Aware Search	Uses bounded search and perception paths whose behavior depends on the workspace.
Typos in function or variable names	Typo-Friendly Smart Matching	Finds what you're looking for even if you or the AI misspell the name.
Ghost servers locking a port	Port Diagnostics	Reports and, where permitted, helps resolve port conflicts; it does not bypass host policy.
Expensive AI bills on long chats	Context and Cache Telemetry	Exposes context behavior and cache signals; provider pricing and savings vary.
Need a smarter model for hard bugs	Swap AI Models Mid-Chat	Switch among the active provider's supported routes without losing context; Claude account routes are discovered from Claude Code when available.
Want a custom AI teammate	Drag & Drop Customization	Drop any notes or script files into a folder to create a personalized AI assistant.

👤 Pick an AI Specialist

Specialist	Best For	What It Does For You
💻 `coder` (Lead Engineer)	Coding & Refactoring	Writes clean code, fixes bugs, cleans up old code, and makes sure tests pass.
🔬 `researcher` (Deep Researcher)	Research & Learning	Searches documentation, summarizes web findings, and gives you verified facts.
🛡️ `sre` (Reliability Engineer)	Fixing Crashes & Errors	Diagnoses error logs, checks system health, and fixes system problems automatically.
✍️ `writer` (Technical Author)	Guides & Documentation	Writes crystal-clear documentation, user guides, and release notes.
🎓 `student` (Patient Mentor)	Learning & Onboarding	Breaks down difficult code into friendly, step-by-step explanations.
⚡ `minimal` (Focused Script)	Focused Automation	Gets straight to work on quick file edits with a deliberately small context.

📋 What's New in Plain English

Feature	What It Means in Everyday Words	Why You'll Love It
⚡ Search & review tools (ADR-136)	• Project-aware search and typo-tolerant matching.• Port diagnostics subject to host permissions.• Diff and sandbox review before supported mutations.	Inspectable workflows whose performance depends on workload and host.
🧠 Context and cache telemetry (ADR-135)	• Tracks reusable context and provider-facing cache signals.• Reports measurements from the configured provider and model.• Keeps cost estimates separate from provider billing.	Better visibility into usage; no universal savings claim.

📜 See the complete release history in CHANGELOG.md.

📚 Advanced Developer Reference

Category	Reference Links
📐 Architecture	Visual Architecture Maps · Runtime Guide · Optimization Record · Master ADR Index
🎓 Research & Evidence	AKD-DSO Academic Paper · Live Baseline Measurements · Benchmark Report · Grand Audit
⚡ Source Architecture	Composition Root · Engine Factory · Tool Registry · Pattern Search Service

Latest Verified Workspace Baseline

The historical run below was generated on 2026-08-17T04:06:43.562Z using Node.js v23.5.0 on macOS ARM64. It passed:

Verification lane	Latest result
Pass 192 composition manifest	566/566 components
Runtime capability smoke	9/9 checks
Heterogeneous benchmark suite	5/5 cases
Complete Flappy Bird React + TypeScript + Vite case	8/8 assertions; 12/12 files
Architecture and performance guardrails	6/6 checks

(Measured fast-path execution throughput for that workload: 8506.11 frames/sec; do not treat it as a universal product metric.)

🏛️ Open Source & License

Inspiration: Built with love and inspired by hermes-agent by Nous Research.
License: Current first-party work is offered under the Apache License 2.0 (LICENSE · NOTICE · CONTRIBUTING.md · PATENT-NON-AGGRESSION-PLEDGE.md). Dependencies retain their own terms, and names/branding are reserved in TRADEMARKS.md.