sudoai

A local-first AI runtime for developers, built as a terminal-native operating layer.

---

📖 About sudoai

sudoai is a cross-platform, terminal-native AI assistant designed to be a daily driver for developers. It runs entirely locally using Ollama for inference, giving you a conversational CLI with full agentic capabilities—file access, shell execution, web search, and persistent memory—without sending your data to the cloud.

The "Operating Layer" Philosophy

Unlike standard chatbots, sudoai operates as a true operating layer. It doesn't just answer questions; it interacts with your environment. Using a sophisticated ReAct (Reason + Act) orchestration engine, it:

1. Analyzes your request.
2. Plans a sequence of tool calls.
3. Executes actions (shell commands, file reads, web scrapes).
4. Reflects on the results to either refine the plan or provide a final answer.

---

🛠️ Installation

Install sudoai-cli globally via npm:

npm install -g sudoai-cli

Prerequisites

• Node.js: v18 or higher.
• Ollama: Must be installed and running (ollama.com).

---

🚀 Quickstart

1. Pull a recommended model:

   ollama pull gemma4:e2b
   

2. Launch the interactive CLI:

   sudoai
   

3. Try an agentic task:

   "Find the latest version of React and create a package.json for a new project."

---

⌨️ Commands Available

While in the interactive session, use these slash-commands for configuration:

Command	Description
/mode	Toggle between simple (standard chat), agent (tools enabled), and research.
/model	List available local models and select your active provider.
/mcp	View status of connected Model Context Protocol servers.
/history	Search and view conversation logs from the local SQLite database.
/bye	Gracefully exit the session.

---

✨ Features

• 🗨️ Conversational CLI — Ultra-fast streaming UI built with Ink/React.
• 🚦 Dynamic Modes — Optimized prompts for standard chat or complex tool-use orchestration.
• 🤖 ReAct Orchestration — High-fidelity agentic loop that avoids hallucination loops.
• 🧰 Native Toolbelt:
  • Shell: Run any CLI command safely through a managed environment.
  • FS: Read, write, and list files across your entire project.
  • Web: Deep search and content extraction via DuckDuckGo and Cheerio.
• 🧠 Smart Memory — Automatically persists conversation history and tool outputs to SQLite.
• 🔌 MCP First — Native support for MCP servers. Add your custom tools in %APPDATA%/sudoai/mcp.json.
• 📁 Contextual @ Syntax — Attach files or directories as context by simply typing @ followed by the filename.
• 🖼️ Multimodal Vision — Pass images to the LLM using --img <path> for analysis or coding help.
• 📜 Virtual Scroll UI — Optimized rendering that handles thousands of lines without performance degradation.

---

🤝 Contribution

Contributions are welcome! Whether it's adding new tools, improving the UI, or optimizing the agent loop:

1. Fork the Project.
2. Create your Feature Branch (git checkout -b feature/AmazingFeature).
3. Commit your Changes (git commit -m 'Add some AmazingFeature').
4. Push to the Branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

Please see CONTRIBUTING.md for detailed guidelines.

---

🏗️ Tech Stack

Layer	Technology
Terminal UI	Ink + React
Logic	TypeScript / Node.js
Inference	Ollama
Scripting	zx
Database	SQLite
State	Zustand
Connectivity	@modelcontextprotocol/sdk

---

🔄 Recent Updates

v1.0.2 — The Stability Update

• Refactored Input Logic: Major fixes to the @ context selector to prevent state desync during rapid typing.
• Scroll Buffering: Implemented a new line-height-aware virtual scroll system for jitter-free rendering.
• Improved Tool Mapping: Enhanced the mapping between user intent and MCP tool selection.
• Windows Path Fixes: Standardized configuration storage in %APPDATA% for Windows users.

---

Built with ❤️ by AMV0027