📖 Overview

SimhaCLI is a powerful terminal-based AI coding agent that brings the intelligence of Large Language Models directly into your development workflow. It reads your code, executes tools, manages sessions, and streams its thinking — all inside your terminal.

SimhaCLI🦁  starting  refactor my auth module
⠦ 🦁 Simha is working... (2.1s)
💭 SimhaCLI thinking (1.3s) The user wants to refactor the auth module...  ▌
💭 thought for 1.3s

I'll read the existing auth module first and then suggest improvements.
SimhaCLI🦁  complete in 14.2s  8821 tokens (8120 prompt + 701 completion)

✨ Features

🤖 Intelligent Agentic Loop

• Multi-turn reasoning — autonomously calls tools, reads results, and continues until the task is done
• Parallel tool execution — runs multiple tool calls simultaneously with asyncio.gather
• Context compression — auto-summarises history when the context window fills up
• Loop detection — detects and breaks repetitive behaviour automatically
• Truncation recovery — handles finish_reason: length gracefully, continues or retries
• Git context awareness — system prompts include current branch, status, and recent commits

📎 File Attachments

• Attach files to prompts — use @attach file.txt or @attach path/to/file.py
• Multiple file support — attach multiple files in a single prompt
• Smart summary — shows attachment count and total size
• Auto-inclusion — file contents are automatically included in the model context

💭 Thinking Display

• Live reasoning — streaming 💭 display shows what the model is thinking in grey italic text
• Running timer — see how long the model has been reasoning
• Collapsed summary — freezes as 💭 thought for X.Xs when reasoning completes (models with extended thinking)

⏱️ Performance Visibility

• Live working spinner — ⠦ 🦁 Simha is working... (10.1s) shows elapsed time
• Total request timer — complete time shown on every response
• Token tracking — complete in 12.4s 8375 tokens (8119 prompt + 256 completion)

🛠️ 16 Built-in Tools

🔌 MCP (Model Context Protocol)

• Connect to any MCP server via stdio or HTTP/SSE transport
• Tools discovered automatically at startup
• Manage connections live with /mcp
• Pre-configured examples for GitHub, PostgreSQL, Supabase, and Playwright
• Vercel deployment uses CLI (npm install -g vercel) — no MCP needed

🚀 Development Workflows

End-to-end automation with a single command or natural language:

Just ask in natural language:

• "Deploy my app to Vercel"
• "Create a GitHub repo and push my code"
• "Set up the database for my project"
• "Build and deploy my full stack app"

Works with MCP servers when configured, falls back to CLI tools automatically.

💾 Session Management

• Every chat is saved automatically to your local data directory — list them with /sessions, read one with /history <n>, and continue it with /resume <n>
• Pick up where you left off from the shell: simhacli --continue (latest chat in this directory) or simhacli --resume <id>
• Create mid-task checkpoints (/checkpoint / /restore <id>)
• Undo the last file edit (/undo)

🔒 Safety & Approval

• Configurable approval policy — from on_request to fully autonomous yolo
• Shell command allowlist/blocklist
• Environment variable masking (API keys, tokens, secrets never leaked to the model)
• Tool permissions — /permissions command to manage tool access (allow/deny specific tools)
• Allowed/denied tools — configure allowed_tools and denied_tools in config.toml

🧩 VS Code Extension

• Sidebar chat backed by the same agent (simhacli serve): same tools, approvals, saved chats, models and API key
• Selection-aware: selected code is added to your message automatically, and Modify / Review / Explain with SimhaCLI appear in the editor's code-action menu
• Approval cards with a real diff view, Revert for the latest changes, in-panel chat history, colour-coded approval modes
• Opens on the right (Secondary Side Bar) and can move to the left. Requires VS Code 1.106+
• See vscode-extension/README.md for setup and settings

🚀 Project Initialization

• /init command — deeply analyzes project structure and generates:
  • AGENTS.md — coding conventions and project guidelines for AI agents
  • SIMHACLI.md — SimhaCLI-specific project context and instructions
• Smart detection — identifies languages, frameworks, and project patterns
• Context-aware — future sessions automatically load these instruction files

🚀 Installation

Prerequisites

• Python 3.10+
• An API key (OpenRouter, OpenAI, Gemini, or any OpenAI-compatible endpoint)

Install from PyPI (Recommended)

pip install simhacli

simhacli                          # interactive mode
simhacli "fix the bug in app.py"  # single prompt
simhacli --help                   # show all options

Install from Source

git clone https://github.com/naidu199/SimhaCLI.git
cd SimhaCLI
pip install -e .
simhacli

⚙️ Configuration

SimhaCLI looks for configuration in two places (project overrides global):

Minimal config.toml

[model]
name = "openrouter/free"
temperature = 1.0

api_key = "your_api_key_here"
api_base_url = "https://openrouter.ai/api/v1"

Set credentials interactively

simhacli
> /credentials

Full config.toml Reference

[model]
name = "openrouter/free"   # any OpenAI-compatible model
temperature = 1.0

api_key = "sk-..."
api_base_url = "https://openrouter.ai/api/v1"

max_turns = 72                  # max agentic loop turns per request
max_tool_output_tokens = 50000  # truncate large tool outputs
approval = "on_request"         # see Approval Policies below
hooks_enabled = true
auto_save_sessions = true   # save every chat locally for /sessions, /history, /resume
developer_instructions = "Always prefer TypeScript over JavaScript."
user_instructions = "Be concise."

# Restrict which tools the agent can use
# allowed_tools = ["read_file", "write_file", "shell"]

[shell_environment]
ignore_default_excludes = false
exclude_patterns = ["*KEY*", "*TOKEN*", "*SECRET*"]

# Add MCP servers
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]

# HTTP/SSE transport
[mcp_servers.my_remote]
url = "http://localhost:8000/sse"

# Add lifecycle hooks
[[hooks]]
name = "format_on_write"
trigger = "after_tool"
command = "black {file}"
enabled = true

Approval Policies

💬 Commands

Type any of these during an interactive session:

🤖 Telegram Bot

Access SimhaCLI remotely from your phone via Telegram:

After setup, your bot will accept messages and commands directly in Telegram. Allowed users can chat with SimhaCLI via the bot.

🔧 Custom Tools

Drop a Python file into <project>/.simhacli/tool/ and SimhaCLI picks it up automatically:

from tools.base import Tool, ToolResult
from pydantic import Field

class MyTool(Tool):
    name = "my_tool"
    description = "Does something useful"

    class Arguments(Tool.Arguments):
        message: str = Field(description="Input message")

    async def execute(self, args: Arguments) -> ToolResult:
        return ToolResult.success_result(f"Got: {args.message}")

Adding Custom MCP Servers

1. Open .simhacli/config.toml

2. Add a new section following one of the patterns:

   Python (recommended):

   [mcp_servers.my_tool]
   command = "uvx"
   args = ["mcp-server-package-name"]
   enabled = true

Node:

   [mcp_servers.my_tool]
   command = "npx"
   args = ["-y", "@scope/server-name"]
   enabled = true

3. Restart SimhaCLI
4. Browse more MCPs: https://github.com/modelcontextprotocol/servers

🖥️ CLI Options

simhacli [OPTIONS] [PROMPT]

Options:
  -c, --cwd DIRECTORY  Set the working directory for the agent
  -r, --resume ID      Continue a saved chat (number from /sessions, or session id / prefix)
  --continue           Continue the most recent chat in this directory
  -v, --version        Show the version and exit
  --help               Show this message and exit

Commands:
  bot    Manage the SimhaCLI Telegram bot
  serve  Run SimhaCLI as a backend for editor extensions (JSON over stdin/stdout)

📝 Changelog

v1.6.0 (October 7, 2026)

• simhacli serve: headless backend for editor extensions (newline-delimited JSON over stdin/stdout)
• VS Code extension (vscode-extension/, installed separately from its .vsix; needs SimhaCLI 1.6.0+): sidebar chat, selection actions, approval cards with diff view, chat history, revert
• Chats are saved automatically; /sessions, /history, /resume, and --resume / --continue to pick one up again
• Safety fixes: shell commands that need approval now prompt under the default policy; actions with no approval handler are denied; allow/deny tool lists are enforced; .. paths can no longer escape the workspace; shell injection in the fullstack workflow closed
• Fixes: orphaned tool calls no longer break a session, large tool output is no longer cleared before the model sees it, /stats, /undo, /run and config saving crashes, Python 3.10 support, wrong MCP package names for sequential-thinking and fetch
• Fixed: simhacli "<prompt>" failed with "No such command" since the bot subcommand was added
• Tool calls are reported as soon as they start (before approval), not only after they finish

v1.5.3 (October 2, 2026)

• Config Saving: Saving config now preserves existing TOML comments and has better error handling
• read_file: Improved code extraction and display logic
• Windows: Consistent console encoding configuration

v1.5.2 (April 5, 2026)

• Image Attachments & Multimodal Messaging in Telegram Bot: Send photos and get AI analysis with vision-capable models
• Enhanced Real-time Progress: Live spinners, tool call tracking, and progressive status updates in Telegram
• Improved Response Formatting: Better loading indicators and agent output presentation

v1.5.0 (April 1, 2026)

• Telegram Bot Integration: Access SimhaCLI remotely from your phone
  • simhacli bot setup — interactive configuration of bot token and allowed users
  • simhacli bot start — start the Telegram bot (runs in foreground)
  • simhacli bot status — show current bot configuration
  • /bot command — show bot setup instructions directly in SimhaCLI
• User Authentication: Telegram bot restricts access to allowed user IDs
• Real-time Bot Status: Visual indicators for bot configuration and readiness
• Improved Configuration Management: Better error handling and setup guidance

v1.4.0 (March 20, 2026)

• Complete Command System Overhaul: New Command pattern with registry for better extensibility

• New Commands:

  • /undo – Undo file changes with interactive selective revert menu
  • /run <command> / !<cmd> – Execute terminal commands directly
  • /workflow <name> [args] – Run development workflows (fullstack, github, push, etc.)

• Live Context Usage Display: See real-time token count vs context window in TUI

• Enhanced Context Management: Actual token counting, pruning at 75%, improved compression at 75% threshold

• Improved Undo: Interactive menu for selective file reversion with safety checks

• Better Model Switching: /model now preserves config file comments and updates system prompt

• Refactored Architecture: Cleaner separation with CommandHandler and command registry

• Enhanced Error Messages: System prompts include context management feedback

v1.3.0 (March 18, 2026)

• Development Workflows: 10 end-to-end workflow actions (fullstack, github, push, install_deps, env_setup, build, readme, database, deploy, tests)
• Natural Language Routing: Agent automatically maps user requests to workflow actions
• Supabase MCP Support: Full Supabase integration alongside PostgreSQL
• Smart Auto-Detection: Package managers, build commands, and project types detected automatically
• MCP Setup Guide: Comprehensive MCP_SETUP_GUIDE.md with step-by-step instructions
• Preserved Config Comments: Changing model via /model no longer strips comments from config.toml
• Enhanced Error Messages: All MCP errors now show setup instructions with config snippets
• Security Improvements: Placeholder values in configs, .gitignore protection for sensitive data

v1.2.0 (March 17, 2026)

• New /init Command: Deeply analyzes projects and generates AGENTS.md and SIMHACLI.md instruction files for better context-aware coding
• New /permissions Command: Manage tool access permissions directly from the CLI
• File Attachment Support: Attach files to prompts using @attach file syntax
• Git Context Integration: System prompts now include git context (branch, status) for enhanced understanding
• Enhanced Error Handling: Improved error handling and logging throughout the agent
• Tool Permission Status: TUI now displays tool permission status (allowed/denied)

v1.1.0 (January 27, 2026)

• Initial public release on PyPI
• 16 built-in tools for file operations, shell commands, web access, and sub-agents
• MCP (Model Context Protocol) support
• Session management with save/resume/checkpoint/restore
• Configurable approval policies
• Thinking display with live reasoning visualization
• Token tracking and performance metrics

🔗 Links

• PyPI: https://pypi.org/project/simhacli/
• GitHub: https://github.com/naidu199/SimhaCLI
• Developer: Narasimha Naidu Korrapati on LinkedIn
• MCP Setup Guide: See MCP_SETUP_GUIDE.md for detailed MCP configuration
• Publishing Guide: See PUBLISHING.md for PyPI deployment instructions