🧠 VisionCode CLI

AI-powered coding agent for your terminal and Telegram — analyze, modify, and plan your codebase with full approval control.

VisionCode is a developer-first CLI tool that brings the power of LLMs directly into your codebase workflow. Ask questions about your code, let an AI agent create, modify, and delete files with a full approval workflow, or generate step-by-step implementation plans — all from your terminal or a Telegram bot.

---

✨ Why VisionCode?

Most AI coding tools lock you into a specific editor or a web UI. VisionCode works where you already are — your terminal — and gives you full control over every change the AI proposes.

• 🛡️ Zero-trust mutations — Every file creation, modification, and deletion is staged in memory. Nothing touches your disk until you explicitly approve it.
• 🔍 Diff-before-apply — Review rich, colorized diffs of every proposed change before accepting.
• 🤖 Multi-mode AI — Choose between Agent, Ask, or Plan mode depending on your task.
• 💬 Telegram integration — Run the same AI agent from a Telegram bot with inline approval buttons.
• 🌐 Any LLM via OpenRouter — Use GPT-4, Claude, Gemini, Llama, Mistral, or any model available on OpenRouter.
• 🔌 Web-aware tools — Optionally enable web search, URL scraping, and crawling via Firecrawl.
• 📝 Beautiful terminal output — Markdown rendered natively in your terminal with syntax highlighting.

---

📦 Installation

Quick install (recommended)

npm install -g visioncode-cli

Then launch:

visioncode wakeup

Using npx (no install)

npx visioncode-cli wakeup

From source (for contributors)

git clone https://github.com/shubham-vaishnav-13/visioncode.git
cd visioncode
bun install
bun run dev

See CONTRIBUTING.md for the full development guide.

---

⚙️ Configuration

Create a .env file in the project root (or wherever you run visioncode):

# Required
OPENROUTER_API_KEY=sk-or-v1-your-api-key-here
OPENROUTER_DEFAULT_MODEL=openrouter/free

# Optional — Telegram bot
TELEGRAM_BOT_TOKEN=your-telegram-bot-token
TELEGRAM_OWNER_ID=your-telegram-user-id

# Optional — Web tools (search, crawl, scrape)
FIRECRAWL_API_KEY=your-firecrawl-api-key

Variable	Required	Description
OPENROUTER_API_KEY	✅	Your OpenRouter API key
OPENROUTER_DEFAULT_MODEL	✅	Model ID (e.g. openrouter/free, anthropic/claude-sonnet-4, google/gemini-2.5-pro)
TELEGRAM_BOT_TOKEN	❌	BotFather token for Telegram mode
TELEGRAM_OWNER_ID	❌	Your Telegram numeric user ID (only the owner can use the bot)
FIRECRAWL_API_KEY	❌	Firecrawl API key for web search & scraping tools

Tip: Copy .env.example to .env and fill in your keys.

---

🚀 Usage

# Launch the interactive mode picker
visioncode wakeup

# Show help
visioncode --help

# Show version
visioncode --version

Mode Picker

When you run visioncode wakeup, you'll see a beautiful ASCII banner and a mode selector:

┌  Which mode you want to proceed with?
│  ○ CLI
│  ○ Telegram
│  ○ Exit
└

Choosing CLI opens the sub-mode menu:

┌  Choose CLI sub-mode
│  ○ Agent Mode
│  ○ Plan Mode
│  ○ Ask Mode
│  ○ ← Back to Main menu
└

---

🤖 Modes

Agent Mode

The full-power AI coding assistant. Describe a task in natural language — the agent reads your codebase, reasons about it, and proposes file changes.

What would you have in mind today for me?
> Add input validation to the user signup endpoint

The agent has access to these tools:

Tool	Description
read_file	Read file contents
create_file	Stage new file creation
modify_file	Stage file modification (full replacement)
delete_file	Stage file deletion
create_folder	Stage folder creation
list_files	List directory contents
search_files	Glob pattern + content search
analyze_codebase	Structure summary (file counts, types)
queue_shell	Queue shell commands for approval
list_skills / read_skill	Access SKILL.md definitions from configured directories
web_search	Search the web (requires Firecrawl)
web_crawl	Scrape a URL into markdown (requires Firecrawl)
fetch_url	HTTP GET any URL

🛡️ All mutations are staged — nothing touches your disk until you approve.

After the agent finishes, you enter the approval flow:

┌  Apply staged changes?
│  ○ Approve and apply all
│  ○ Review one by one        ← view diffs per file
│  ○ Cancel
└

Ask Mode

A read-only Q&A mode. Ask any question about your codebase — the agent reads files and searches for answers, but cannot modify anything.

What do you want to ask the codebase?
> How does the authentication middleware work?

The answer is rendered as beautiful markdown in your terminal. You can optionally save it to a .md file in the ask-mode/ directory.

Plan Mode

Describe a high-level goal and the AI generates a structured, step-by-step implementation plan — with complexity ratings. You select which steps to execute, and the agent carries them out one by one.

What is your goal?
> Migrate the database layer from Prisma to Drizzle ORM

The plan includes:

• 📊 Research summary — what the AI learned about your codebase
• 📋 Numbered steps — with title, description, hints, and complexity (low / medium / high)
• ✅ Step selector — toggle which steps to execute
• 🔧 Auto-execution — each selected step runs through the agent with full approval flow

---

💬 Telegram Bot

Run VisionCode as a Telegram bot — same AI capabilities, but from your phone.

Setup

1. Create a bot with @BotFather and get the token
2. Get your numeric Telegram user ID (use @userinfobot)
3. Add both to your .env:

   TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
   TELEGRAM_OWNER_ID=123456789

4. Start VisionCode and select Telegram mode

Bot Commands

Command	Description
/start	Show welcome message and available commands
/ask <question>	Ask a question about the codebase (read-only)
/agent <task>	Run the full agent with file mutation capabilities
/plan <goal>	Generate and execute a step-by-step plan

Telegram Approval Flow

When the agent proposes file changes, you get inline buttons:

• 📋 Show Diff — view the unified diff of all changes
• ✅ Accept All — apply all changes to disk
• ❌ Reject All — discard everything

For Plan mode, you get an interactive step selector with toggle buttons, Select All / Deselect All, and a Proceed button.

Security: Only the TELEGRAM_OWNER_ID can interact with the bot. All other users are silently ignored.

---

🏗️ Project Structure

visioncode/
├── index.ts                         # CLI entry point (Commander.js)
│
├── ai/
│   ├── ai.config.ts                 # OpenRouter model setup
│   └── index.ts                     # AI module exports
│
├── modes/
│   ├── cli.ts                       # CLI sub-mode selector
│   ├── agent/
│   │   ├── orchestrator.ts          # Agent loop & tool orchestration
│   │   ├── agent-tools.ts           # Tool definitions (Vercel AI SDK)
│   │   ├── tool-executor.ts         # File/shell operations with in-memory overlay
│   │   ├── action-tracker.ts        # Append-only action log
│   │   ├── approval.ts             # Interactive terminal approval flow
│   │   ├── diff-view.ts             # Unified diff generation
│   │   └── types.ts                 # Shared types & default config
│   ├── ask/
│   │   ├── orchestrator.ts          # Ask mode loop (read-only agent)
│   │   └── agent-tools.ts           # Read-only tool subset
│   └── plan/
│       ├── orchestrator.ts          # Plan generation → step execution
│       ├── planner.ts               # AI-powered plan generator (structured output)
│       ├── selection.ts             # Interactive step selector UI
│       └── types.ts                 # Plan & PlanStep interfaces
│
├── telegram/
│   ├── index.ts                     # Telegraf bot startup
│   ├── handlers.ts                  # Command & callback handlers
│   ├── agent-run.ts                 # Telegram agent/ask/plan runners
│   ├── approval-session.ts          # Inline approval buttons & diff
│   ├── plan-session.ts              # Interactive plan step toggle
│   ├── auth.ts                      # Owner-only guard
│   ├── constants.ts                 # Welcome message
│   └── text.ts                      # Text utilities (clip, replyMd)
│
├── feature/
│   └── web-tools.ts                 # Firecrawl-powered web search/crawl/fetch
│
├── tui/
│   ├── wakeup.ts                    # ASCII banner & mode picker
│   ├── terminal-md.ts               # Markdown → terminal renderer
│   └── loader.ts                    # Braille spinner animation
│
├── scripts/
│   └── add-shebang.js               # Post-build shebang injector
│
├── tsconfig.json                    # Dev config (Bun, bundler resolution)
├── tsconfig.build.json              # Build config (Node.js, NodeNext)
└── package.json

---

🧩 Architecture

In-Memory Overlay

The agent never writes directly to disk. All file mutations (create, modify, delete) are staged in an in-memory Map<string, string> overlay. The overlay acts as a virtual filesystem layer — reads fall through to disk, but writes are captured.

Action Tracker

An append-only log records every operation the agent performs. Each entry tracks:

• Type: file_create, file_modify, file_delete, folder_create, tool_execute, code_analysis
• Status: pending → approved / rejected → executed
• Before/After content for diffs

Approval Flow

Pending mutations are grouped by file path. For each group, you can:

1. View the unified diff
2. Accept or reject the change
3. Or approve/reject everything in bulk

Only after approval does applyApprovedFromTracker() write to disk.

AI Pipeline

User prompt
    ↓
ToolLoopAgent (Vercel AI SDK)
    ↓
LLM (via OpenRouter) ←→ Tool calls (read_file, create_file, etc.)
    ↓
Staged mutations in overlay
    ↓
Approval flow (terminal or Telegram)
    ↓
Apply to disk

---

🔗 Tech Stack

Technology	Purpose
Vercel AI SDK	ToolLoopAgent, structured output, tool definitions
OpenRouter	LLM provider gateway (GPT-4, Claude, Gemini, etc.)
Commander.js	CLI argument parsing
@clack/prompts	Beautiful terminal prompts (select, text, confirm)
Telegraf	Telegram bot framework
Firecrawl	Web search & scraping
marked + marked-terminal	Markdown → terminal rendering
diff	Unified diff generation
figlet	ASCII art banner
chalk	Terminal colors
Bun	Development runtime
TypeScript	Type-safe codebase

---

📄 License

MIT

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

• Local development setup
• Import conventions
• Build system details
• Publishing to npm
• Architecture notes

---

🔗 Links

• npm: npmjs.com/package/visioncode-cli
• GitHub: github.com/shubham-vaishnav-13/visioncode
• OpenRouter: openrouter.ai

---

_{Built with ❤️ by Shubham Vaishnav}