Skip to main content

SamCode CLI

PyPI version Python Version License: MIT

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

  • 🧠 Vector-Based Codebase Memory (RAG): The agent automatically indexes your workspace and uses semantic search to find code by meaning, not just keywords.
  • 🩺 Proactive Code Doctor: When you ask to fix or optimize code, the agent automatically runs static analysis (like ruff) to find bugs and linting issues before generating a solution.
  • 📊 Senior Data Analyst & BI Mode: Toggle /data or just ask to analyze a dataset. The agent reads CSV, Excel, Parquet, SQL databases, and more. It can generate publication-quality charts and automatically save the workflow as a production-ready Jupyter Notebook (.ipynb).
  • 🎨 Expert Frontend Architect Mode: Toggle /frontend to transform the AI into a Senior UI/UX Engineer that creates bespoke design systems, custom color palettes, and modern CSS architectures (no generic AI templates).
  • 🚀 Advanced Execution Environment:
    • [EXECUTE_SCRIPT]: Runs Python, Node.js, Go, etc., in a dedicated side-terminal so you can watch the execution live.
    • [EXECUTE_NOTEBOOK]: Executes Jupyter Notebooks cell-by-cell and saves the outputs directly into the file.
  • 💾 Continuous Session Memory: The agent remembers your project goals and previous conversation turns across the session, stored securely in .samcode/session_memory.json.
  • 🤫 Token Economy & Stream Masking: The agent never wastes tokens printing raw code in the chat. It masks generation with clean status indicators like ✨ Generating... or 📖 Reading....
  • 🛡️ Auto-Security & Dotfile Protection: Automatically detects and adds config files (.env, .vscode, etc.) to your .gitignore to prevent accidental pushes of sensitive data.
  • 🌐 Universal AI Support: Connect to 15+ providers (OpenAI, Anthropic, Google Gemini, Ollama, Groq, etc.) with dynamic model fetching.
  • 🌿 Native Git Integration: A full interactive Git workflow (/git) to commit, push, pull, branch, and stash without leaving the agent.
  • ⌨️ Advanced Shortcuts: Emacs-style navigation (Ctrl+A, Ctrl+W, Home/End) in the prompt for fast typing.

🚀 Installation

Install SamCode CLI globally from PyPI using pip:

pip install samcode-cli

📖 Commands Reference

🤖 Core & AI Modes

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).
/frontend Toggle Expert Frontend Architect Mode(bespoke design systems).
/data Toggle Senior Data Analyst & BI Mode(datasets, SQL, notebooks).
/aboutme Information about the developer and SamCode.

🧠 Memory & Codebase

Command Description
/reindex Re-build the vector memory index after major code changes.
/clear-memory Clear the session conversation history.
/upload <path> Upload & extract documents (PDF, DOCX, XLSX, PPTX, Images).
/clear-uploads Clear uploaded documents from the session context.

🌐 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.

🛠️ Autonomous Tools (No Commands Needed)

Just ask the agent naturally, and it will use these tools automatically:

  • [SEARCH_SEMANTIC] **: Finds relevant code across your entire project based on context (e.g., ** "Where is the authentication logic?" ).
  • [EXECUTE_SCRIPT] : Opens a side terminal to run scripts (Python, JS, Go, Rust, etc.) and monitors the process.
  • [EXECUTE_NOTEBOOK] : Runs all cells in a Jupyter Notebook and saves the execution outputs.
  • [CHECK_PROCESS] : Verifies if a background script or execution is still running.
  • [WRITE_FILE] / [READ_FILE] : Creates, reads, and modifies files with a beautiful side-by-side diff preview.

🛡️ 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.
  • Auto-Ignore Dotfiles : The agent automatically scans for hidden config files (.env, .idea, .vscode) and adds them to .gitignore to prevent leaking secrets.
  • User Approval : All file modifications, terminal commands, and dependency installations require your confirmation before execution.
  • 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

Metadata

Release files for samcode-cli 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for samcode-cli 1.3.0
File Size Uploaded Provenance Actions
samcode_cli-1.3.0.tar.gz 58.3 kB Without provenance Details for samcode_cli-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for samcode-cli 1.3.0
File Interpreter ABI Platform Actions
samcode_cli-1.3.0-py3-none-any.whl Python 3 none any Details for samcode_cli-1.3.0-py3-none-any.whl

Total release size: 118.4 kB

Release files / samcode_cli-1.3.0.tar.gz

Download URL samcode_cli-1.3.0.tar.gz
Size 58.3 kB
Tags Source
SHA-256 checksum
How to use checksums
1801e262045d1cff8b8e6cc974357ef0a4fe97e4547f7053d2848698c39925fb
BLAKE2b-256 checksum
How to use checksums
1c271e0dc5a5f43fd4aa1aae7e9b0086e66e3d37bfecf30f52af29e808d7decf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.11

Release files / samcode_cli-1.3.0-py3-none-any.whl

Download URL samcode_cli-1.3.0-py3-none-any.whl
Size 60.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6dd80462ab891eb001c3f4007ba2f0be8f1b286eb527b2e35ca2079a292c1006
BLAKE2b-256 checksum
How to use checksums
778cdfbfc3af24058c599838617d091dc473880ff950b257b7754ac1df0f6390
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.11

Security for samcode-cli 1.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page