Markdown Chat (mdchat) ✨

Collaborate with LLMs directly in your terminal.
Ask, edit, summarize, and generate content inline in Markdown.

---

🚀 Features

• 📝 Ask questions and insert AI answers directly into .md files.
• ✍️ Edit sections with AI-powered rewrites (simplify, clarify, shorten, etc.).
• 📚 Summarize long notes or papers into concise takeaways.
• 📄 Generate blog posts and documentation in Markdown.
• 💬 Interactive chat mode with an LLM inside your terminal.

All AI-generated content is wrapped in <!-- AI: ... --> blocks, so you always know what’s machine-written.

---

📦 Installation

# install globally
npm install -g mdchat

# or run once via npx
npx mdchat --help

Requirements: Node.js 20+

---

⚡ Quick Start

# 1) 30‑second interactive setup
mdchat config setup

# 2) Ask your first question
mdchat ask "What is machine learning?"

---

🎯 Commands

Ask Question

# Ask a question (streaming by default for better UX)
mdchat ask "What is the capital of France?"

# Disable streaming if you prefer to see the complete response at once
mdchat ask "Explain quantum computing" --no-stream

# Save the answer to a file
mdchat ask "How does photosynthesis work?" -o biology.md

Insert Context-Aware Content

# Insert AI-generated content into marked blocks based on surrounding context
mdchat insert document.md

# Preview what will be generated without making changes
mdchat insert document.md --preview

# Save to a different file instead of modifying the original
mdchat insert document.md -o enhanced-document.md

To use the insert command, add HTML comment markers in your markdown file:

# My Document

Existing paragraph about topic A.

<!-- AI insert here -->
<!-- AI insert end -->

Existing paragraph about topic B.

The AI will analyze the surrounding context and generate connecting content that flows naturally between the paragraphs.

Summarize Content

# Summarize a single file
mdchat summarize document.md

# Summarize multiple files with glob patterns
mdchat summarize "docs/*.md"

# Summarize an entire directory
mdchat summarize ./research/

# Save summary to a file
mdchat summarize notes.md -o summary.md

Edit Content

# Simplify a section
mdchat edit document.md --section "Complex Topic" --action simplify

# Expand on a topic
mdchat edit article.md --section "Introduction" --action expand

# Clarify technical content
mdchat edit guide.md --section "Setup" --action clarify

Configuration

# Interactive setup (recommended for first-time users)
mdchat config setup

# Manual configuration
mdchat config set provider openai
mdchat config set model gpt-4o
mdchat config set apiKey your-api-key

# View current configuration
mdchat config list

Sections (list headings in a file)

# Show all headings with line numbers
mdchat sections README.md

---

⚙️ Global Options

• --provider <provider>: AI provider (openai, anthropic, ollama)
• --model <model>: Model to use (gpt-4o, claude-3-5-sonnet-20241022, llama3.2, etc.)
• --api-key <key>: API key for the provider
• --base-url <url>: Custom API base URL (for ollama or custom endpoints)

---

🎨 Examples

Ask a question (streaming by default):

mdchat ask "Write a comprehensive guide to Node.js best practices"

Summarize multiple research papers:

mdchat summarize "research/papers/*.md" -o research-summary.md

Edit and improve a blog post:

mdchat edit blog-post.md --section "Conclusion" --action expand

---

🔧 Environment Setup

Set your API key as an environment variable:

export OPENAI_API_KEY="your-api-key-here"
# or  
export ANTHROPIC_API_KEY="your-anthropic-key"

Or configure it via the CLI:

mdchat config --api-key your-api-key

---

📝 Output Format

All AI responses are wrapped in HTML comments for easy identification:

Your AI-generated content appears here.

This makes it clear what content was generated by AI vs. human-written.

---

🔌 Providers & Models

• OpenAI: default provider. Common model: gpt-4o.
  • Env: set OPENAI_API_KEY or run mdchat config setup and paste your key.
• Anthropic (Claude): set --provider anthropic --model claude-3-5-sonnet-20241022.
  • Env: set ANTHROPIC_API_KEY.
• Ollama (local): run ollama serve, install a model (e.g., ollama pull llama3.2).
  • Use --provider ollama --model llama3.2 and optionally --base-url http://localhost:11434.

You can also persist these choices using:

mdchat config set provider openai
mdchat config set model gpt-4o
mdchat config set apiKey YOUR_KEY

---

🖥️ OS-specific env examples

• macOS/Linux (bash/zsh):

export OPENAI_API_KEY="sk-..."

• Windows PowerShell:

$env:OPENAI_API_KEY = "sk-..."

• Windows CMD:

set OPENAI_API_KEY=sk-...

---

❓ Troubleshooting / FAQ

• "No provider/model configured"

  • Run mdchat config setup or pass --provider/--model on the command.

• "401/Forbidden or invalid API key"

  • Verify your key is set (mdchat config list) or env var is exported in the current shell.

• Ollama errors like "connection refused" or "model not found"

  • Start server: ollama serve
  • Install model: ollama pull llama3.2
  • Then run with --provider ollama --model llama3.2.

• Streaming looks odd in files

  • Use --no-stream to print a complete response at once.

• Save outputs to a file

  • Use -o notes.md to append AI blocks to a markdown file.