A mush code pre-processor written in TypeScript
npm install @digibear/mush-format

MUSH Format is an intelligent, AI-powered build tool and pre-processor for
MUSHcode (TinyMUSH, PennMUSH, MUX, RhostMUSH, etc.). Write clean, modern,
readable code ā and let the agentic system autonomously analyze, format, and
heal your code into production-ready MUSH scripts.
Write code like a developer. Let AI handle the rest.
---
MUSH Format doesn't just compile code ā it understands it. Our agentic
workflow powered by LangGraph and Google Gemini provides:
- Automatically discovers your project structure
- Identifies entry points and dependencies
- Supports mform.config.ts/js for custom configuration
- Processes #include, @define, templates, and all directives
- Handles multi-file projects with automatic bundling
- Preserves source mapping for debugging
- Heuristic healing for common errors (unterminated strings, etc.)
- LLM-powered healing for complex syntax issues using RAG with MUX
documentation
- Detects and fixes:
- Unbalanced brackets [] and parentheses ()
- @ commands inside function calls
- Complex nested expression errors
- Parallel batch processing (30 concurrent fixes) for speed
- Validates formatted output
- Reports remaining errors with detailed diagnostics
- Provides confidence in your build
---
``bash`
npm install -g @digibear/mush-format
1. Initialize a new project:
`bash`
mform init my-game
cd my-game
2. Write clean code (src/index.mush):`
mush`
// Define a hello command
&CMD_HELLO #123=$hello *:
@pemit %#=Hello, %0!
@pemit %#=Welcome to the game.
3. Build with agentic mode (default):
`bash`
mform run . -o build.txt
The agent will:
- ā Analyze your project
- ā Parse and bundle files
- ā Compress and optimize
- ā Detect and heal syntax errors
- ā Verify the output
4. Output (build.txt):`
mush`
&CMD_HELLO #123=$hello *:@pemit %#=Hello, %0!;@pemit %#=Welcome to the game.
---
- LLM Self-Healing: Automatically fixes complex syntax errors using Google
Gemini 2.5 Flash
- RAG Integration: Leverages MUX documentation for context-aware fixes
- Parallel Processing: Heals up to 30 errors simultaneously for speed
- Write indented, commented, readable code
- Use // comments (removed) and @@ MUSH comments (preserved)/ /
- Block comments supported
- mform init to scaffold new projectsmform install github:user/repo
- for dependenciesmform.config.ts/js
- Configuration via or legacy mush.json
- Imports: #include ./file.mush or from URLs@define MACRO(args) { body }
- Macros: for code reuse#for
- Templates: , #if for code generation@test
- Testing: framework for unit tests
- Documentation: Auto-generate help from JSDoc comments
- Minification and compression
- Installer script generation (-i flag)-w
- Watch mode () for development-d
- Diff mode () for incremental updates
---
Create .env.local in your project root:
`env`
GOOGLE_API_KEY=your_api_key_here
Or set globally:
`bash`
mform run . --google-api-key=your_key
Without an API key, complex errors are detected but not automatically
healed.
mform.config.ts (recommended):
`typescript`
export default {
mform: {
main: "./src/index.mush",
},
include: ["src//.mush", "lib//.mu"],
dependencies: {
"utils": "github:mushcoder/mush-utils",
},
};
Legacy mush.json:
`json`
{
"main": "./src/index.mush",
"dependencies": {
"utils": "github:mushcoder/mush-utils"
}
}
---
`mush
// Import from local files
#include ./utils/helpers.mush
// Import from URLs
#include https://raw.githubusercontent.com/user/repo/main/lib.mu
// Include file content as MUSH comments
#file ./LICENSE
`
Define reusable code patterns:
`mush
@define EMIT_TO_ROOM(msg) {
@remit %l=msg
}
@define SET_ATTR(obj, attr, val) {
&attr obj=val
}
EMIT_TO_ROOM(The room shakes!)
SET_ATTR(%#, HEALTH, 100)
`
Generate code programmatically:
`mush
// Loops
#for i in range(1, 5) {
&STAT_%i #123=%i
}
// Conditionals
#if (ENV == "dev") {
@debug Development mode active
}
`
`mush
@test "Math functions" {
add(2, 2)
} expect {
4
}
@test "String ops" {
cat(Hello, World)
} expect {
HelloWorld
}
`
Run tests (when implemented):
`bash`
mform test
Generate @help entries from comments:
`mush
@help_object #123
@help_pre &HELP_
/**
* +attack
*
* Initiates combat with the specified target.
* Requires you to be in the same room.
*/
&CMD_ATTACK #123=$+attack *:
// Implementation
`
Generates:
`mush`
&HELP_ATTACK #123=+attack
---
| Command | Alias | Description |
| --------------------- | ----- | ----------------------------------------- |
| mform run | r | Build project with agentic mode (default) |mform init
| | i | Create new project scaffold |mform install
| | add | Install dependency from GitHub |mform github
| | git | Format remote file from GitHub |mform purge
| | p | Clear diff caches |
`bash
mform run
Options:
-o, --output
-d, --diff Show only changes from previous build
-w, --watch Watch mode - rebuild on file changes
-i, --install-script Generate installer script format
--no-agent Disable agentic mode (classic formatter)
--google-api-key
`
`bashBuild with agentic healing
mform run . -o build.txt
---
šØ Modern CLI Output
MUSH Format features a beautiful, accessible CLI with:
- šØ Vibrant colors for different message types
- ā Semantic icons (success, error, warning, info)
- š Progress indicators during healing
- šÆ Clear sections for workflow stages
`
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
AGENTIC MODE ACTIVATED
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
Analyzing Project: /path/to/project
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā Config loaded from: mform.config.ts
āø Found 45 potential source files
ā
Entry Point: index.mush
[=============================] 100% | ā Batch 1-30 complete
ā Successfully healed all errors!
ā Parsing Complete: 1,234 lines
ā Successfully formatted 1,234 lines
`---
šļø Architecture
MUSH Format uses LangGraph for workflow orchestration:
`
START ā Analyzer ā Parser ā Compressor ā Linter ā² Verifier ā END
ā ā
āāāāāāāāā
Self-Healing Loop
(max 3 iterations)
`$3
1. Analyzer: Discovers files, entry points, and configuration
2. Parser: Processes all directives and generates formatted output
3. Compressor: Strips comments, joins lines, optimizes
4. Linter: Detects errors and initiates healing
5. Verifier: Validates final output
$3
1. Simple errors ā Heuristic fixes (instant)
2. Complex errors ā LLM healing with RAG context
3. Batch processing ā 30 parallel API calls for speed
4. Re-verification ā Ensures fixes are correct
---
š® Coming Soon
Exciting features on the roadmap to make MUSH development even better:
$3
- [ ] VSCode Extension - Syntax highlighting, IntelliSense, live preview, and one-click builds
- [ ] Language Server Protocol (LSP) - Full IDE support with autocomplete, go-to-definition, and refactoring
- [ ] Interactive Playground - Web-based editor to experiment with mform syntax and see instant results
- [ ] Live Reload - Hot module replacement for instant feedback during development
$3
- [ ] GitHub Actions Integration - Automated builds and deployments on every commit
- [ ] Pre-commit Hooks - Automatic formatting and linting before commits
- [ ] Deployment Pipelines - Push directly to MUSH game servers from CI/CD
- [ ] Version Tagging - Semantic versioning for MUSH packages
$3
- [ ] Incremental Builds - Only reprocess changed files for faster rebuilds
- [ ] Smart Caching - Persistent cache for includes and dependencies
- [ ] Build Profiles - Optimize for development vs. production builds
- [ ] Parallel Processing - Multi-threaded parsing for massive projects
$3
- [ ] Enhanced Test Runner - Execute
@test blocks with detailed reports and coverage
- [ ] Agentic Testing - mform test command that runs tests against live MUSH server
- [ ] Test Generation - AI-powered test case generation from code
- [ ] Integration Testing - Test against live MUSH server instances
- [ ] Code Coverage Reports - Track which code is tested
- [ ] Performance Profiling - Identify slow commands and bottlenecks
- [ ] Snapshot Testing - Track and verify command output over time$3
- [ ] Visual Debugger - Step through code execution with breakpoints
- [ ] Dependency Graph Viewer - Visualize project structure and imports
- [ ] Refactoring Tools - Automated code transformations and modernization
- [ ] Code Metrics Dashboard - Complexity analysis, duplication detection, and quality scores
$3
- [ ] Cloud-Based Healing - No API key required - healing as a service
- [ ] Package Registry - Discover, share, and install community packages
- [ ] Collaborative Editing - Real-time multiplayer coding sessions
- [ ] Version Control Integration - Git workflow optimized for MUSH code
$3
- [ ] Agentic Create -
mform create to generate new code from natural language
- [ ] Agentic Modify - mform modify to edit code via AI
- [ ] AI Code Suggestions - Context-aware autocomplete powered by LLM
- [ ] Automatic Refactoring - AI-suggested improvements and modernizations
- [ ] Code Review Assistant - Automated best practice recommendations
- [ ] Natural Language Commands - "Create a combat system" ā Generated scaffold
- [ ] Intent-Based Healing - AI understands what you're trying to do and fixes accordingly$3
- [ ] Direct Server Upload - Deploy code directly to your game server
- [ ] Live Data Sync - Two-way sync between code and server
- [ ] Remote Debugging - Debug code running on the server
- [ ] Server Health Monitoring - Track performance and errors in real-time
$3
- [ ] Interactive Tutorials - Learn mform with hands-on examples
- [ ] Recipe Library - Pre-built templates for common patterns
- [ ] Best Practices Guide - Advanced techniques and optimization tips
- [ ] Video Courses - Comprehensive learning materials
---
ļæ½š¤ Contributing
Contributions welcome! This project is actively developed.
1. Clone:
git clone https://github.com/digibear-io/mush-format.git
2. Install: npm install
3. Build: npm run build
4. Test: npm test`---
MIT Ā© Digibear
---
- GitHub:
digibear-io/mush-format
- npm:
@digibear/mush-format
- Issues: Report a bug
---
Made with ā¤ļø for the MUSH community