@shigar/muaz

v0.0.2

Published

3 days ago

AI agent CLI with embedded API and UI

Downloads

270

0High
0Medium
0Low

mannaan

muaz

A terminal-first LLM agent platform. Chat with AI agents, run multi-agent pipelines, and install plugins — all from a single binary. Agents are model-agnostic and bind to a model through named provider profiles (OpenAI-compatible, Google Gemini, local Ollama, or AWS Bedrock).

Installation

macOS / Linux

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/shigar-dev/releases-muaz/releases/latest/download/muaz-installer.sh | sh

macOS (Homebrew)

brew tap shigar-dev/muaz
brew install muaz

Windows (PowerShell)

irm https://github.com/shigar-dev/releases-muaz/releases/latest/download/muaz-installer.ps1 | iex

Windows (MSI)

Download muaz-x86_64-pc-windows-msvc.msi from the releases page and run the installer.

npm (any platform)

npm install -g @shigar/muaz

From source

git clone https://github.com/shigar-dev/muaz
cd muaz
cargo build --release -p muaz
cp target/release/muaz ~/.local/bin/   # or anywhere on $PATH

On first run, muaz bootstraps ~/.muaz/ with sensible defaults.

Quick start

export OPENAI_API_KEY=sk-...

muaz chat                        # open the default agent
muaz chat --agent coding         # open the coding agent
muaz chat --incognito            # don't save the session to disk
muaz chat --session <id>         # resume a previous session

The REPL opens immediately. Type your message and press Enter. Use /help to see all slash commands.

Directory layout

After the first run, ~/.muaz/ looks like this. Authored content lives inside plugins — your own in the local workspace, shared ones under plugins/, and read-only defaults under builtins/:

~/.muaz/
├── config.yaml          # global settings (default agent + provider, approval, telemetry)
├── providers.yaml       # named provider profiles (model connections)
├── plugins.yaml         # per-plugin state (enabled / priority / trusted / source)
├── mcp.json             # global MCP server registry
├── builtins/
│   └── default/         # embedded read-only `default` agent (refreshed each start)
├── plugins/
│   ├── local/           # YOUR workspace
│   │   ├── agents/      #   agents you create
│   │   ├── skills/      #   each skill is a dir with a SKILL.md
│   │   ├── pipelines/   #   multi-agent pipeline definitions
│   │   ├── prompts/
│   │   └── commands/    #   custom slash commands
│   ├── coding/          # seeded example plugin (editable)
│   └── <installed>/     # plugins you install
├── sessions/            # saved sessions + index.json
├── runtimes/            # on-demand Node.js / uv runtimes for MCP servers
└── memory/              # reserved for future memory backends

Configuration

Global config (`~/.muaz/config.yaml`)

# The agent used when no --agent flag is passed
default_agent: default

# Provider/model selection. default_provider names a profile from providers.yaml;
# agent_providers overrides specific agents. See "Providers" below.
default_provider: gemini-main
agent_providers:
  coding:
    profile: bedrock-work

# Override the remote plugin registry index (else $MUAZ_PLUGIN_REGISTRY, else default)
# plugin_registry: "https://example.com/muaz-plugins/index.json"

# Global tool approval policy (per-agent settings override these)
tool_approval:
  auto_approve:
    - "fetch_webpage:*"   # always approve without prompting
  auto_deny:
    - "shell:rm -rf *"    # always deny without prompting
  prompt:
    - "shell:*"           # ask the user every time
    - "edit_file:*"
    - "patch_file:*"

Provider profiles (`~/.muaz/providers.yaml`)

Agents are model-agnostic. Define named provider profiles once and bind them via default_provider / agent_providers above:

gemini-main:
  type: gemini
  model: gemini-2.5-pro
  api_key: ${GEMINI_API_KEY}

bedrock-work:
  type: bedrock
  region: us-east-1
  model: anthropic.claude-3-5-sonnet-20241022-v2:0
  profile: work

Effective provider for an agent resolves as: per-agent override → default_provider → the agent's own inline provider: block → error.

MCP registry (`~/.muaz/mcp.json`)

MCP server definitions live in their own JSON file. Use muaz mcp install to manage entries, or edit it directly:

[
  {
    "transport": "stdio",
    "name": "filesystem",
    "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
  },
  {
    "transport": "http",
    "name": "my-api",
    "url": "http://localhost:3000/mcp"
  }
]

Agent config (`~/.muaz/plugins/local/agents/<name>.yaml`)

name: coding
description: "An expert coding assistant"

# Provider is OPTIONAL — omit it to stay model-agnostic and use the global
# default profile. Include it only to pin a model for this agent:
# provider:
#   type: openai-compatible
#   model: gpt-4o
#   api_key: "${OPENAI_API_KEY}"   # ${ENV_VAR} interpolation supported

# system_prompt: path (~/…, /…, ./…, ../…) OR inline text. Co-locate and use a
# relative path so the agent is portable across namespaces.
system_prompt: "./coding.md"

# Optional: path to a markdown SOP file appended after system_prompt
sop_file: "./coding-sop.md"

streaming: true   # stream tokens as they arrive (default: true)

# Agentic loop limits (null = use built-in default)
max_iterations: 20         # tool-call rounds before giving up
max_concurrent_tools: 4    # parallel tool executions per round

# LLM inference parameters (null = use model default)
max_tokens: ~
temperature: ~

# Compact conversation history when accumulated input tokens exceed this threshold.
# null disables compaction.
compaction_token_threshold: 80000

# Custom compaction summarization instructions (null = use built-in default)
compaction_summary_prompt: ~

# Agent Skills configuration
# skills:
#   paths: []     # extra search paths
#   allow: []     # allowlist by name
#   deny: []      # denylist by name

# Restrict to a subset of built-in tools
built_in_tools:
  include_tools:
    - edit_file
    - shell
    - fetch_webpage

# MCP server filter for this agent
mcp_servers:
  - name: filesystem

# Per-agent tool approval (evaluated before global policy)
tool_approval:
  auto_approve:
    - "fetch_webpage:*"
    - "shell:git *"
    - "shell:cargo *"
  prompt:
    - "shell:*"
    - "edit_file:*"
  auto_deny:
    - "shell:rm *"

Approval pattern format: "tool_name:glob" where the glob is matched against the JSON-serialised args. * matches everything. Examples:

| Pattern | Matches | |---|---| | fetch_webpage:* | any fetch_webpage call | | shell:*git* | shell commands containing git | | shell:rm -rf * | exact prefix match |

Resolution order: session-approved → agent auto_approve → agent auto_deny → global auto_approve → global auto_deny → interactive prompt.

At the interactive prompt:

a — approve once
s — approve for this session
d — deny once
D — deny always (persisted to config.yaml)

Supported providers

| type | Notes | |---|---| | openai-compatible | OpenAI, Together.ai, Groq, Ollama, any OpenAI-compatible endpoint | | bedrock | AWS Bedrock (uses ambient AWS credentials) | | gemini | Google Gemini (generativelanguage.googleapis.com) | | ollama | Locally-running Ollama server |

Each provider type accepts only its own fields — unknown fields are rejected with a clear error.

Bedrock example:

provider:
  type: bedrock
  model: us.anthropic.claude-sonnet-4-6-20251001-v1:0
  region: us-east-1          # optional; falls back to AWS_DEFAULT_REGION → AWS_REGION → us-east-1
  timeout_secs: 120          # optional
  profile: my-aws-profile    # optional; AWS credential profile
  endpoint_url: "https://vpce-xxx.bedrock-runtime.us-east-1.vpce.amazonaws.com"  # optional; VPC endpoint

Gemini example:

provider:
  type: gemini
  model: gemini-2.5-flash
  api_key: "${GEMINI_API_KEY}"
  timeout_secs: 60
  thinking_budget: 8192      # token budget for extended thinking (0 = off)
  # thinking_mode: "medium"  # alternative: low / medium / high / max

Ollama example:

provider:
  type: ollama
  base_url: "http://localhost:11434"
  model: llama3.2
  timeout_secs: 120
  keep_alive: "5m"           # optional; how long Ollama keeps the model loaded
  think: "high"              # optional; thinking mode: enabled / high / medium / low

CLI reference

muaz <COMMAND>

Commands:
  chat      Start an interactive chat session
  run       Run one non-interactive turn and print the result (scriptable)
  pipeline  Run or list multi-agent pipelines
  agents    Manage agents
  skills    Manage Agent Skills
  plugins   Install and manage plugins (agents, skills, pipelines, prompts)
  config    View and edit global configuration
  mcp       Manage MCP server registrations
  runtime   Manage bundled MCP runtimes (Node.js, uv)
  gateway   Start the web server with browser UI
  doctor    Diagnose config, runtimes, and MCP server health

Running bare muaz (no subcommand) starts interactive chat with the default agent.

`muaz chat`

muaz chat [OPTIONS]

Options:
  -a, --agent <AGENT>       Agent to load (default: value in config.yaml)
      --incognito           Do not save session to disk
      --session <SESSION>   Resume an existing session by ID
      --remember-approvals  Persist "approve for session" grants into the
                            session file and restore them on resume

`muaz run`

Run a single non-interactive turn and print the result. Useful for scripting and piping.

muaz run [PROMPT] [OPTIONS]

Arguments:
  [PROMPT]   The prompt (combined with piped stdin when both are present)

Options:
  -a, --agent <AGENT>     Agent to use (default: value in config.yaml)
      --session <SESSION> Append this turn to an existing session
      --output <FORMAT>   text (default) or json
      --incognito         Do not save the session

Examples:
  muaz run "summarise this file" < README.md
  git diff | muaz run "review this change"
  muaz run "what day is it?" --output json

`muaz pipeline`

muaz pipeline <COMMAND>

Commands:
  run <name> [input]   Run a pipeline (reads stdin when input is omitted and piped)
  list                 List pipelines in your local workspace

`muaz gateway`

Start the Axum web server with the embedded React UI. The first browser request opens the UI at http://localhost:<port>.

muaz gateway [OPTIONS]

Options:
  -p, --port <PORT>   Port to listen on (default: 7878)
      --host <HOST>   Bind address (default: 127.0.0.1; use 0.0.0.0 to expose
                      to the network — muaz will warn you)
      --token <TOKEN> Shared secret for all requests (default: $MUAZ_GATEWAY_TOKEN,
                      else a freshly generated token printed at startup)

`muaz doctor`

Check the installation: config validity, bootstrapped layout, bundled runtime status, and MCP server reachability.

muaz doctor

`muaz agents`

muaz agents <COMMAND>

Commands:
  list          List all available agents
  create        Create a new agent interactively
  show <name>   Show the full config of an agent
  edit <name>   Open an agent config in $EDITOR

`muaz skills`

muaz skills <COMMAND>

Commands:
  list          List all discovered skills
  create        Create a new skill interactively
  show <name>   Show the SKILL.md of a skill
  edit <name>   Open a skill's SKILL.md in $EDITOR

`muaz plugins`

Install and manage plugins — bundles of agents, skills, pipelines, and prompts.

muaz plugins <COMMAND>

Commands:
  install <target>   Install from a local .zip path, or by registry name (name@version)
  search <query>     Search the remote registry
  list               List installed plugins (enabled/disabled, trusted) + built-ins
  show <id>          Show a plugin's manifest and contents
  enable <id>        Enable a disabled plugin
  disable <id>       Disable a plugin without uninstalling it
  uninstall <id>     Uninstall a plugin (deletes its directory)

Options (install):
  --force            Overwrite an existing plugin with the same id

Provider profiles have no dedicated subcommand — edit ~/.muaz/providers.yaml and muaz config edit, or use the browser UI's Providers page.

`muaz config`

muaz config [COMMAND]

Commands:
  show      Print the current config.yaml
  edit      Edit config fields interactively (default)
  validate  Check config.yaml, agents, mcp.json, and pipelines for problems

`muaz mcp`

muaz mcp <COMMAND>

Commands:
  install <spec>   Register an MCP server (npm package, uvx package, or HTTP URL)
  list             List all registered MCP servers
  remove <name>    Remove a registered MCP server by name

Options (install):
  --name <name>   Override the derived server name
  --uvx           Use uvx (uv tool run) instead of npx
  [args...]       Extra arguments passed to the server process (stdio only)

`muaz runtime`

Manages the Node.js and uv runtimes that muaz downloads on demand for MCP servers.

muaz runtime <COMMAND>

Commands:
  list             Show installed runtime status and pinned versions
  install [name]   Download a runtime now (node | uv; omit to install what's needed)
  update           Re-download installed runtimes to refresh pinned versions
  clean            Remove all downloaded runtimes

Slash commands

| Command | Description | |---|---| | /help | Show all commands | | /agents | List agents across all namespaces | | /switch <name> | Load a different agent, start a fresh session | | /mcp | Show MCP server connection status | | /tools | List registered tools and their approval policy | | /session | Show current session metadata (id, model, message count) | | /sessions | Browse recent sessions; choose one to resume | | /run <name> [input] | Run a multi-agent pipeline | | /pipelines | List pipelines in your local workspace | | /skills | List available Agent Skills | | /skill <name> | Show the body of a skill's SKILL.md | | /incognito | Toggle incognito mode (session not saved) | | /compact | Summarize and compact conversation history now | | /usage | Show token and latency stats for this session | | /clear | Start a fresh session (old transcript stays saved) | | /exit | Exit muaz |

Custom commands defined in ~/.muaz/commands/<name>.yaml also appear in /help.

Built-in tools

| Tool | Description | |---|---| | edit_file | Overwrite a file with new content (creates if missing) | | patch_file | Apply a unified diff patch to an existing file | | shell | Execute a shell command via sh -c and return combined stdout/stderr | | fetch_webpage | Fetch a URL and return the page content as plain text |

MCP tools are also registered when MCP servers are connected.

Agent Skills

Skills are reusable instruction sets that the agent can load on demand. Each skill lives in its own directory containing a SKILL.md file.

Skill discovery paths

Skills are discovered from these locations (in order of precedence):

<cwd>/.muaz/skills/ and <cwd>/.agents/skills/ — project-level
~/.muaz/plugins/local/skills/ — your local workspace
installed plugin skills/ directories
built-in skills/ directories

Local/project skills are trusted automatically; a plugin skill's allowed-tools are pre-approved only when the plugin is trusted.

SKILL.md format

---
name: my-skill
description: A short description shown in listings
compatibility: muaz>=1.0     # optional
allowed-tools: shell:git * fetch_webpage:*  # optional; space-separated tool patterns
---

# my-skill

Full skill instructions go here. The agent reads this file when it wants to use the skill.

Skill catalog in prompts

When skills are discovered, the agent's system prompt gets an appended ## Available Skills block listing each skill's name, description, and SKILL.md path. The agent reads the file when it wants to invoke a skill.

Managing skills via CLI

muaz skills list               # show all discovered skills with scope
muaz skills create             # interactive wizard to create a new skill
muaz skills show my-skill      # print the SKILL.md of a skill
muaz skills edit my-skill      # open SKILL.md in $EDITOR

From within the REPL:

/skills            list available skills
/skill my-skill    print a skill's SKILL.md

Pipelines

Pipelines wire multiple agents together for complex workflows. Define them as YAML files in ~/.muaz/plugins/local/pipelines/ and run with /run <name> [input].

Sequential pipeline

Each agent's output becomes the next agent's input.

# ~/.muaz/plugins/local/pipelines/research-and-write.yaml
name: research-and-write
pattern: sequential
steps:
  - agent: researcher          # resolved across namespaces (local, plugins, built-ins)
    pass: last_message         # pass only the last output (default)
  - agent: writer
    pass: full_history         # prepend all prior step I/O as context

pass modes:

last_message — the previous agent's response becomes the next agent's input (default)
full_history — all prior step inputs and outputs are prepended as context

Parallel pipeline

All agents run concurrently with the same input. Results are merged with per-agent section headers.

name: multi-review
pattern: parallel
agents:
  - reviewer-a
  - reviewer-b
  - reviewer-c
merge: concat    # default; 'summary' will be added in a future release

Router pipeline

A router agent reads the input and returns a JSON routing decision. The message is then forwarded to the selected downstream agent.

name: smart-dispatch
pattern: router
router_agent: dispatcher     # must be a fast, cheap model (e.g. gpt-4o-mini)
routes:
  coding: coding-agent       # key → agent name
  research: research-agent
  default: default-agent     # fallback if no route matches

The router agent automatically receives routing instructions appended to its system prompt and is expected to reply with:

{"route": "coding", "message": "Fix the authentication bug"}

If the response cannot be parsed, the input is forwarded to the default route.

Custom slash commands

Drop a YAML file in ~/.muaz/plugins/local/commands/ to add a custom / command:

# ~/.muaz/plugins/local/commands/deploy.yaml
name: deploy
description: "Deploy to staging"
command: "cd ~/project && make deploy-staging"

The command runs via sh -c. Environment variables available:

| Variable | Value | |---|---| | MUAZ_SESSION_ID | Current session UUID | | MUAZ_AGENT_NAME | Current agent name | | MUAZ_MODEL | Current model identifier |

Session management

Sessions are saved to ~/.muaz/sessions/ as JSON files (one per session). An index.json tracks metadata for the last 20 sessions.

Use --session <id> to resume a session on startup
Use /sessions to browse and resume from within the REPL
Use --incognito or /incognito to skip saving

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme