AI#

Mandu ships first-class terminal-based AI tooling. A streaming chat playground, a non-interactive eval harness, a prompt template system, four new MCP tools for agents, a pure loop-closure framework, and an auto skills generator — all under the mandu ai namespace or wired into @mandujs/mcp and @mandujs/skills.

# Streaming chat with a local Ollama instance (no API key required)
mandu ai chat --provider=local

# One-shot eval across multiple providers
mandu ai eval --prompt="Summarize this repo" \
  --providers=local,claude,openai

Providers at a glance#

The local provider ships a deterministic echo responder that works with no API key — ideal for CI, smoke tests, and demos. Set MANDU_LOCAL_BASE_URL=http://127.0.0.1:11434 to hit a real Ollama or LM-Studio instance.

Pages#

• Chat — mandu ai chat REPL, slash commands, history schema.
• Eval — mandu ai eval non-interactive harness, cross-provider comparison.
• Prompts — prompt template system, adapters architecture, presets.
• MCP tools — 4 new tools: run.tests, deploy.preview, ai.brief, loop.close.
• Loop closure — pure detector/emitter framework for recognizing stall patterns.
• Skills generator — @mandujs/skills auto-skill-manifest generator.

Security posture#

1. API keys never logged. All error messages mask tokens as sk-***. The adapter layer never surfaces the raw key.
2. Bun.secrets fallback. If the env var is absent, mandu ai reads from OS keychain (macOS Keychain, Windows Credential Manager, Linux libsecret).
3. Slash-command arguments are escaped. /preset ../etc is rejected by a strict alphanumeric allow-list before any file open.
4. Non-UTF8 / NUL-containing input is rejected with CLI_E308 so it never hits the adapter's HTTP body.
5. mandu.loop.close is pure. No fs, no spawn, no fetch. Output is advisory text — an orchestrator decides whether to feed it back into the agent.

Troubleshooting#

🤖 Agent Prompt#

Apply the guidance from the Mandu docs page at https://mandujs.com/docs/ai/index to my project.

Summary of the page:
AI category hub. Four providers: claude, openai, gemini, local (echo + Ollama/LM-Studio). Two CLI commands: `mandu ai chat` (REPL) + `mandu ai eval` (non-interactive). Phase 14 ships: 4 new MCP tools (run.tests, deploy.preview, ai.brief, loop.close), prompt templates, loop closure framework.

Required invariants — must hold after your changes:
- Four providers: `claude`, `openai`, `gemini`, `local` (Ollama/LM-Studio compatible)
- API keys NEVER logged — errors mask them as `sk-***`
- Local provider echo responder works offline with no API key — deterministic, CI-safe
- History JSON schema v1 — `/save` produces portable exports
- MCP tool `mandu.loop.close` is pure — no I/O, no spawn, advisory text only

Then:
1. Make the change in my codebase consistent with the page.
2. Run `bun run guard` and `bun run check` to verify nothing
   in src/ or app/ breaks Mandu's invariants.
3. Show me the diff and any guard violations.

Related#

• MCP tools — how the 4 new tools plug into @mandujs/mcp.
• Build with Agents — MCP setup — wire Claude Code / Cursor / Continue / Aider.
• CLI — mcp register — automated merge-safe registration.

For Agents#

{
  "schema": "mandu.ai/v0.25",
  "commands": {
    "chat": "mandu ai chat",
    "eval": "mandu ai eval"
  },
  "providers": ["claude", "openai", "gemini", "local"],
  "env_vars": {
    "claude": "MANDU_CLAUDE_API_KEY",
    "openai": "MANDU_OPENAI_API_KEY",
    "gemini": "MANDU_GEMINI_API_KEY",
    "local": "MANDU_LOCAL_BASE_URL (optional)"
  },
  "mcp_tools": [
    "mandu.run.tests",
    "mandu.deploy.preview",
    "mandu.ai.brief",
    "mandu.loop.close"
  ],
  "rules": [
    "API keys are never logged — adapter layer masks as sk-***",
    "Local provider works offline with deterministic echo — CI-safe",
    "loop.close is pure: no I/O, advisory text only"
  ]
}