chat.md: The Hacker's AI Chat Interface [Experimental]

Finally, a fully editable chat interface with MCP support on any LLM.

chat.md is a Visual Studio Code extension that reimagines AI interaction through plain text files. Unlike ephemeral web interfaces or proprietary chat windows, chat.md embraces a file-first approach where your conversations with AI are just markdown files with a .chat.md extension. Edit them, version control them, share them - they're your files. The AI directly writes its response in the file.

Any '*.chat.md' file is now an AI agent hackable by you. Go crazy with non linear AI conversation.

Usage video

Here's the chat I used to publish this vscode extension using gemini-2.5-pro and wcgw mcp

NOTE ⚠️: chat.md is 100% AI coded and should be treated as a feature rich POC.

Why chat.md?

Features

🗣️ File-Based Conversations

Unlike Copilot's inline suggestions, ChatGPT's web interface, or Cursor's side panel, chat.md treats conversations as first-class files in your workspace:

# %% user
How can I optimize this function?

[#file](src/utils.js)

# %% assistant
Looking at your utils.js file, I see several opportunities for optimization:

1. The loop on line 24 could be replaced with a more efficient map/reduce pattern
2. The repetitive string concatenation can be improved with template literals
...

🔌 Universal Model Support

• Anthropic Claude: All models (Opus, Sonnet, Haiku)
• OpenAI: GPT-4, GPT-3.5, and future models
• Custom APIs: Any OpenAI-compatible endpoint (Azure, Google Gemini, etc.)
• Quick Switching: Toggle between different models in between a conversation.

🛠️ Universal Tool Ecosystem with MCP

Chat.md is a Model Context Protocol (MCP) client - an open standard for tool execution that works with any LLM.

Chat.md doesn't restrict any LLM from tool calling unlike many chat applications.

• Truly Universal: Any AI model (Claude, GPT, open-source models) can use any MCP tool
• Model Agnostic: Tools work identically regardless of which AI powers your conversation
• No Vendor Lock-in: Switch models without losing tool functionality

<tool_call>
<tool_name>filesystem.searchFiles</tool_name>
<param name="pattern">*.js</param>
<param name="directory">src</param>
</tool_call>

📎 Contextual File Attachments

• Attach text files and images directly in your conversations (paste any copied image)
• Link files using familiar markdown syntax: [file](path/to/file)
• Files are resolved relative to the chat document - perfect for project context (or use absolute paths)

💾 Editable Conversations

Since chat.md files are just text, you have complete control over your AI interactions:

• Non-linear Editing: Rewrite history by editing earlier parts of the conversation
• Conversation Hacking: Put words in the AI's mouth by editing its responses
• Continuation Control: Have the AI continue from any edited point
• Resume Truncated Outputs: If an AI response gets cut off, just add a new assistant block and continue
• Git-Friendly: Track conversation changes, collaborate on prompts, and branch conversations
• Conversation Templates: Create reusable conversation starters for common tasks

Getting Started

Quick start

1. Install 'chat.md' from the VS Code marketplace
2. Configure your API key(s):
   • Command Palette → "Add or Edit API Configuration"
3. Create a new chat:
   • Opt+Cmd+' (Mac) / Ctrl+k Ctrl+c (Windows/Linux) to create a new '.chat.md' file with workspace information populated in a user block.
   • Or create any file with the .chat.md extension anywhere and open it in vscode.
4. In a '# %% user' block write your query and press 'Shift + Enter' (or just create a new '# %% assistant' block and press enter)
5. Watch the assistant stream its response and do any tool call.

Optionally you can start a markdown preview side by side to get live markdown preview of the chat which is more user friendly.

Usage info

• You can insert a # %% system block to append any new instructions to the system prompt.
• You can manually add API configuration and MCP configuration in vscode settings. See example settings
• Click on the live status bar "Chat.md streaming" icon in the bottom or run "chat.md: Cancel streaming" command to interrupt
• You can also use the same shortcut "Opt+Cmd+'" to cancel streaming as for creating a new chat.
• You can run command "Refresh MCP Tools" to reload all mcp servers. Then run "MCP Diagnostics" to see available mcp servers.
• You can use "Select api configuration" command to switch between the API providers

Configuration

chat.md supports a three-level configuration system with the following precedence (highest to lowest):

1. File-specific configuration - Set at the top of individual .chat.md files
2. Provider-specific configuration - Set in VS Code settings for each API provider
3. Global configuration - Default VS Code settings

File-specific Configuration

Configure parameters at the beginning of any .chat.md file:

selectedConfig="my-provider"
reasoningEffort="high"
maxTokens=4000
maxThinkingTokens=20000

# %% system
Your system prompt here

VS Code Settings

Access these through VS Code's settings UI or settings.json:

• chatmd.apiConfigs: Named API configurations (provider, API key, model, base URL, plus optional reasoning/token settings)
• chatmd.selectedConfig: Active API configuration
• chatmd.mcpServers: Configure MCP tool servers
• chatmd.reasoningEffort: Global reasoning depth (none, minimal, low, medium, high)
• chatmd.maxTokens: Global maximum response tokens
• chatmd.maxThinkingTokens: Global maximum thinking tokens

Tool Execution

When an AI response includes a tool call, the extension will automatically:

1. Add a tool_execute block after the assistant's response
2. Execute the tool with the specified parameters
3. Insert the tool's result back into the document
4. Add a new assistant block for the AI to continue

You can also trigger tool execution manually by:

• Pressing Shift+Enter while positioned at the end of an assistant response containing a tool call
• This will insert a tool_execute block and execute the tool

Keyboard Shortcuts

• Shift+Enter: Insert next block (alternates between user/assistant) or inserts a tool_execute block if the cursor is at the end of an assistant block containing a tool call
• Opt+Cmd+' (Mac) / Ctrl+k Ctrl+c' (Windows/Linux): Create new context chat or cancel existing streaming

MCP Tool Integration

Connect any Model Context Protocol server to extend AI capabilities:

Local MCP Servers (stdio)

For local MCP servers running in the same environment as VS Code:

"chatmd.mcpServers": {
  "wcgw": {
    "command": "uvx",
    "args": [
      "--python",
      "3.12",
      "--from",
      "wcgw@latest",
      "wcgw_mcp"
    ]
  }
}

Remote MCP Servers (Streamable HTTP)

chat.md supports the new Streamable HTTP transport from the MCP spec 2025-11-25, which replaces the older HTTP+SSE transport. This is the recommended way to connect to remote MCP servers.

"chatmd.mcpServers": {
  "remote-mcp": {
    "url": "https://example.com/mcp",
    "transport": "streamable-http"
  }
}

You can also pass custom HTTP headers (e.g. for authentication):

"chatmd.mcpServers": {
  "remote-mcp": {
    "url": "https://example.com/mcp",
    "transport": "streamable-http",
    "headers": {
      "Authorization": "Bearer your-token-here"
    }
  }
}

Transport auto-detection

By default, the transport field is "auto" — chat.md will try the new Streamable HTTP transport first, and automatically fall back to the legacy SSE transport if the server doesn't support it. You can explicitly set the transport to "streamable-http", "sse", or "auto":

Remote MCP Servers (Legacy SSE)

For older remote MCP servers that only support the deprecated HTTP+SSE transport:

"chatmd.mcpServers": {
  "remote-mcp": {
    "url": "http://localhost:3000/sse",
    "transport": "sse"
  }
}

You can also add environment variables if needed:

"chatmd.mcpServers": {
  "remote-mcp": {
    "url": "http://localhost:3000/sse",
    "transport": "sse",
    "env": {
      "API_KEY": "your-api-key-here"
    }
  }
}

The AI will automatically discover available tools from both local and remote servers and know how to use them! Tool lists are refreshed automatically every 5 seconds to keep them up-to-date. All MCP servers are initialized concurrently, so a slow or failing server won't block the others.

The Philosophy

chat.md breaks away from the artificial "chat" paradigm and acknowledges that AI interaction is fundamentally about text processing. By treating conversations as files:

1. Persistence becomes trivial - no special cloud sync or proprietary formats
2. Collaboration is built-in - share, diff, and merge like any other code
3. Version control is natural - track changes over time
4. Customization is unlimited - edit the file however you want

Limitations

1. MCP -- only tools supported, prompts and resources will be supported in the future.
2. Caching not yet supported in anthropic api.
3. Gemini, ollama, llm studio and other models have to be accessed using openai-api only.

Example vscode settings

vscode json settings

  "chatmd.apiConfigs": {
    "gpt-5.2": {
      "type": "openai",
      "apiKey": "",
      "model_name": "gpt-5.2",
      "reasoningEffort": "none"
    },
    "gemini-2.5pro": {
      "type": "openai",
      "apiKey": "",
      "base_url": "https://generativelanguage.googleapis.com/v1beta/openai/",
      "model_name": "gemini-2.5-pro-exp-03-25"
    },
    "anthropic-sonnet-3-7": {
      "type": "anthropic",
      "apiKey": "sk-ant-",
      "base_url": "",
      "model_name": "claude-3-7-sonnet-latest",
      "maxTokens": 6000,
      "maxThinkingTokens": 18000
    },
    "openrouter-qasar": {
      "type": "openai",
      "apiKey": "sk-or-",
      "base_url": "https://openrouter.ai/api/v1",
      "model_name": "openrouter/quasar-alpha"
    },
    "groq-llam4": {
      "type": "openai",
      "apiKey": "",
      "base_url": "https://api.groq.com/openai/v1",
      "model_name": "meta-llama/llama-4-scout-17b-16e-instruct"
    },
    "together-llama4": {
      "type": "openai",
      "base_url": "https://api.together.xyz/v1",
      "apiKey": "",
      "model_name": "meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8"
    }
  },
  "chatmd.mcpServers": {
    
    "wcgw": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "tool",
        "run",
        "--python",
        "3.12",
        "--from",
        "wcgw@latest",
        "wcgw_mcp"
      ]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": ""
      }
    },
    "fetch": {
      "command": "/opt/homebrew/bin/uvx",
      "args": ["mcp-server-fetch"]
    }
  },
  "chatmd.selectedConfig": "gemini-2.5pro",
  "chatmd.maxTokens": 8000,
  "chatmd.maxThinkingTokens": 16000,
  "chatmd.reasoningEffort": "medium"

Configuration Notes:

• maxTokens (default: 8000) controls the maximum number of tokens for model responses
• For OpenAI reasoning models (o1, o3 series), maxTokens is used as the total max_completion_tokens budget (includes both thinking and response tokens)
• For Anthropic models, maxThinkingTokens controls the thinking token budget separately, or can be calculated automatically from reasoningEffort
• Provider-specific configurations override global settings, and file-specific configurations override both (see CONFIGURATION.md for detailed precedence rules)

License

MIT License - see the LICENSE file for details.

Feedback & Contributions

• File issues on the GitHub repository
• Contributions welcome via pull requests

Credits

• Claude with wcgw mcp
• Gemini 2.5 pro with chat.md