samcode-cli 1.0.3

An autonomous AI coding agent that runs in your terminal.

SamCode CLI

SamCode CLI is a powerful, autonomous AI coding agent that runs directly in your terminal. Similar to Claude Code and GitHub Copilot Workspace, it reads your project structure, writes and edits code, executes terminal commands, and fixes its own errors—all while keeping your workflow secure and efficient.

✨ Key Features

• 🤖 Autonomous Agentic Loop: The agent thinks in steps. It reads files, writes code, runs commands, and automatically fixes terminal errors or reviews its own code for bugs.
• 🌐 Universal AI Support: Connect to 15+ providers (OpenAI, Anthropic, Google Gemini, Ollama, Groq, etc.) with dynamic model fetching.
• 📄 Universal Document Reader: Upload and analyze PDFs, Word docs, Excel sheets, PowerPoint presentations, and images directly in the chat.
• 🔍 Live Web Search: Use /searchweb to open your browser and let the AI synthesize answers from live search results.
• Project Scaffolding: Use /init to instantly scaffold projects for React, Next.js, Django, Spring Boot, Flutter, Rust, and more.
• 🌿 Native Git Integration: A full interactive Git workflow (/git) to commit, push, pull, branch, and stash without leaving the agent.
• 📦 Auto Dependency Installation: Automatically detects missing packages and installs them with your approval.
• 🔒 Path Sandboxing: The agent is restricted to your workspace and asks for explicit permission before accessing files outside the current directory.
• ⌨️ Advanced Shortcuts: Emacs-style navigation (Ctrl+A, Ctrl+W, Home/End) in the prompt for fast typing.
• Caveman Mode: Save tokens with ultra-concise, grunt-like AI responses.

🚀 Installation

Install SamCode CLI globally from PyPI using pip:

pip install samcode-cli

Commands Reference

🤖 Core & AI

Command	Description
/connect	Configure AI provider and API key interactively.
/models	Dynamically fetch and select models from your provider.
/caveman	Cycle through token-saving modes (OFF ➔ BASIC ➔ ULTRA).
/deps	Toggle auto-approve for dependency installations.
/aboutme	Information about the developer and SamCode.

📂 Files & Documents

Command	Description
/upload <path>	Upload & extract documents (PDF, DOCX, XLSX, PPTX, Images).
/clear-uploads	Clear uploaded documents from the session context.
/read-file <path>	Read any file using the universal document reader.

🌐 Web & Scaffolding

Command	Description
/searchweb <query>	Search the web (opens browser) & get an AI-synthesized answer.
/init <name>	Scaffold a new project (React, Django, Spring, Flutter, etc.).

🌿 Git Operations

Command	Description
/git	Open the interactive Git menu (Status, Commit, Push, Pull, Branches, Diff, Stash).

⚙️ System

Command	Description
/help	Show all available commands.
/clear	Clear the terminal screen.
/exit	Exit SamCode CLI.

⌨️ Keyboard Shortcuts

**SamCode CLI uses **prompt_toolkit to provide a rich input experience. The following shortcuts work directly in the prompt:

• Ctrl + A : Select all text
• Ctrl + W : Delete word backward
• Ctrl + U : Clear line backward
• Ctrl + K : Delete to end of line
• Home / End : Jump to start/end of line
• Shift + Home/End : Select to start/end of line
• Ctrl + Left/Right : Jump by word

🛡️ Safety & Security

• Path Sandboxing **: By default, the agent cannot read, write, or execute commands outside the directory where you launched **samcode. If it needs to, it will pause and ask for your explicit permission.
• User Approval **: All file modifications, terminal commands, and dependency installations require your confirmation before execution (unless auto-approve is enabled via **/deps).
• Self-Review : After writing code, the agent automatically reviews its own work to catch syntax errors or logical bugs before moving on.

Requirements

• Python 3.8 or higher
• An API key for your chosen AI provider (OpenAI, Anthropic, Google, etc.)
• Internet connection (except when using local Ollama models)

📝 License

**This project is licensed under the MIT License. See the **LICENSE file for details.

---

Developed by Magra Houssem Eddine