Markov CLI

A powerful terminal-based AI coding agent that reads files, edits code, runs commands, and researches the web — all from your command line.

✨ Features

🎯 Multiple Agent Modes

Choose the right mode for your task:

• /agent — Full autonomy mode with file operations, shell access, and automatic task execution
• /ask — Read-only Q&A mode for exploring codebases without modifications
• /plan — Draft a task plan, approve it, then watch it execute with automatic progress tracking
• /orchestrator — Decompose complex tasks into parallel subagents for faster execution
• /research — Deep research with web search, generating beautiful HTML reports
• /init — Analyze your codebase and generate comprehensive project documentation

🔧 Powerful Tool System

Markov has direct access to:

• File Operations — Read, write, edit, delete, and search through files; edits inside the project are auto-approved, anything outside the project asks first
• Shell Commands — Execute bash commands with built-in safety controls (confirmation required unless YOLO is on)
• Configurable Permissions — /permissions checkbox picker decides what needs approval and what YOLO auto-approves
• Web Search — Research documentation and solutions online
• Subagents — Spawn specialized agents for focused tasks
• Memory — Persistent facts about your projects and preferences
• Thinking Control — Toggle model reasoning with /think (on/off, effort low–max), mapped per provider (Ollama think, DeepSeek thinking+reasoning_effort, OpenAI reasoning_effort, Claude extended thinking); env overrides MARKOV_THINKING/MARKOV_THINKING_EFFORT. The default is off — no thinking params, thinking disabled where supported. With thinking on, the reasoning stays hidden: the panel shows a "Thinking…" spinner and logs ✓ Thought for Xs when the model finishes reasoning, then the answer streams normally.

🎨 Beautiful Terminal UI

• Live Markdown Rendering — Formatted headings, code blocks, tables, and links as they stream
• Smart Input — Multi-line editing, history navigation, and file picker
• Token Gauge — Real-time context window tracking
• Spinner & Progress — Visual feedback for long-running operations

💡 IDE Integration

The VS Code extension provides seamless IDE integration:

• Automatically shares your active file, cursor position, and selection
• No copy-pasting required — just type your question
• Works with VS Code and Cursor
• Secure loopback-only connection

🌐 Multiple AI Providers

Connect to your preferred AI service:

• Anthropic Claude
• OpenAI
• DeepSeek
• OpenRouter (Qwen, Llama, DeepSeek, and many more via one API)
• Local Ollama
• Ollama Cloud

Switch providers on-the-fly with /model — no restart needed.

📁 File References

Attach files to your prompts using @path syntax:

@src/app.js what does this file do?

Directories expand recursively, and images are automatically encoded.

💾 Sessions & Memory

• Persistent Sessions — Every conversation is saved; switch between projects with /session
• Long-term Memory — Facts about your projects persist across sessions; inspect with /memory and size the budget with /memory-ctx <tokens>
• Context Compaction — /compact summarizes long conversations to save tokens

⚡ YOLO Mode

Toggle auto-approval of all tool calls (including bash and require-confirm commands) with --yolo flag or Ctrl+Y for lightning-fast workflows. Catastrophic commands (e.g. rm -rf /) stay blocked in every mode.

🚀 Quick Start

Installation

npm install -g markov-cli

Setup

1. Add your API key:

markov
# In the CLI: /connect
# Choose your provider and enter your API key

2. Start chatting:

markov

VS Code Extension (Optional)

For IDE integration, install the Markov VS Code extension:

code --install-extension markov-vscode

Run markov in VS Code's integrated terminal, and the CLI will automatically access your active file and selection.

📖 Usage

Basic Commands

markov              # Start interactive mode
markov --yolo       # Start with auto-approval enabled
markov --help       # Show help

Inside the CLI

Modes

• /agent <task> — Full autonomy mode
• /ask <question> — Read-only Q&A
• /plan <goal> — Plan and execute
• /research <topic> — Deep research with web search
• /orchestrator <task> — Parallel task decomposition

Productivity

• /session — Switch between project sessions
• /compact — Summarize conversation to save tokens
• /clean — Clear screen
• /clear — Start fresh conversation

Configuration

• /model — Switch AI provider/model
• /models — Configure visible models
• /modes — Customize available modes
• /permissions — Choose what requires approval & what YOLO auto-approves
• /think — Show/set the thinking preference (on/off, effort low–max; default off)
• /connect — Add API keys
• /yolo — Toggle auto-approval (Ctrl+Y)

Context

• @path/to/file — Attach files to your prompt
• /ide — Check IDE connection status
• /ctx — View context window usage

Help

• /help — Show all commands
• /skills — Browse skill guides
• /balance — Check API usage/credits

🎯 Examples

Refactor Code

/agent refactor @src/api.js to use async/await

Research & Report

/research best practices for React performance optimization

Plan Complex Tasks

/plan add user authentication with JWT tokens, including signup, login, and protected routes

Ask Questions

/ask @src/ how does the authentication flow work?

Generate Agent Documentation

/init

Analyzes your entire codebase and generates a comprehensive markov.md project guide.

🛠️ Configuration

Markov looks for a .env file in your current directory or uses ~/.markov/ for global config.

Environment Variables

# AI Provider Keys
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
DEEPSEEK_API_KEY=sk-...
OPENROUTER_API_KEY=sk-or-...
OLLAMA_API_KEY=...

# Search
MARKOV_SEARCH_API_KEY=...  # Serper.dev for web search

# Options
MARKOV_YOLO=1              # Auto-approve all tools
MARKOV_IDE=0               # Disable IDE integration
MARKOV_DEBUG=1             # Enable debug logging
MARKOV_THINKING=1          # Thinking preference: 1/on or 0/off (default: off — no thinking)
MARKOV_THINKING_EFFORT=high  # Effort: low | medium | high | max (default low; when on)

Custom Models

Add custom models with /add-model or edit ~/.markov/models.json:

{
  "enabled": ["claude-5-opus", "gpt-5.6"],
  "custom": ["custom-model@openai"]
}

🏗️ How It Works

1. Raw Terminal UI — Hand-built TUI with ANSI escape codes (no framework bloat)
2. Mode System — Task-specific tool sets and prompts
3. Tool Execution — Parallel tool calls; in-project edits auto-approved, outside-project use and bash require confirmation
4. Streaming — Real-time markdown-formatted responses
5. Session Management — JSONL-based conversation persistence

📁 Project Structure

bin/            CLI entry point
src/
  interactive/  REPL loop + mode engine (modes/turn.js) + thin mode wrappers
  commands/     slash-command handlers + registry
  agent/        agent loop + shared tool-execution (toolLoop.js)
  tools/        tool registry + execution (local/, services/)
  providers/    LLM provider layer (facade: index.js, routing: registry.js)
  config/       ~/.markov config read/write (modeRegistry, permissions, …)
  core/         editor, files, input, skills
  ui/           screen, panel, spinner, streaming, formatting, theme, debug
  utils/        configStore, fetchRetry, planParser, projectState
  billie/       virtual-cat companion
docs/           ARCHITECTURE.md, markov.md, markov-demo.html
skills/         skill guides (*.md)

See docs/ARCHITECTURE.md for the full layer map and data flow.

📄 License

MIT © [Your Name]

🔗 Links

• NPM Package: npmjs.com/package/markov-cli
• VS Code Extension: Markov for VS Code

Built with the crappy first version of the cli