{"id":25925573,"url":"https://github.com/laelhalawani/ai-shell-agent","last_synced_at":"2025-06-29T22:34:14.096Z","repository":{"id":278993527,"uuid":"937428374","full_name":"laelhalawani/ai-shell-agent","owner":"laelhalawani","description":"A command-line AI chat application that helps perform tasks by writing and executing terminal commands with user supervision and by answering questions.","archived":false,"fork":false,"pushed_at":"2025-05-21T20:29:26.000Z","size":590,"stargazers_count":31,"open_issues_count":7,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-23T15:54:06.249Z","etag":null,"topics":["agents","ai","automation","cli","cmd","llm","open-source","shell"],"latest_commit_sha":null,"homepage":"https://laelhalawani.github.io/ai-shell-agent/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/laelhalawani.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-23T02:53:31.000Z","updated_at":"2025-06-11T02:58:32.000Z","dependencies_parsed_at":null,"dependency_job_id":"648e5377-8170-4093-80ef-724457ea0e10","html_url":"https://github.com/laelhalawani/ai-shell-agent","commit_stats":null,"previous_names":["laelhalawani/shellai"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/laelhalawani/ai-shell-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laelhalawani%2Fai-shell-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laelhalawani%2Fai-shell-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laelhalawani%2Fai-shell-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laelhalawani%2Fai-shell-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/laelhalawani","download_url":"https://codeload.github.com/laelhalawani/ai-shell-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laelhalawani%2Fai-shell-agent/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262678626,"owners_count":23347401,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","automation","cli","cmd","llm","open-source","shell"],"created_at":"2025-03-03T18:51:08.720Z","updated_at":"2025-06-29T22:34:14.082Z","avatar_url":"https://github.com/laelhalawani.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Shell Agent\n\n---\n\n**🚀 Version 0.2.0 Released! 🚀**\n\nWe're excited to announce the release of `ai-shell-agent` version 0.2.0! This version brings greatly improved functionality, modularity, and new features including enhanced toolsets, better configuration management, and localization support.\n\n**Upgrade is highly recommended for all users:**\n\n```bash\npip install --upgrade ai-shell-agent\n```\n\n---\n\n**AI Shell Agent** is a command-line LLM-powered assistant designed to streamline your development and system administration tasks directly within your terminal. It interacts with your system through modular **Toolsets**, understanding your requests, planning actions, and leveraging capabilities like **Terminal execution**, **File System Management** (both with user confirmation), and experimental **AI-powered file editing** (via `aider-chat`). It maintains conversation context, adapts its available actions based on enabled toolsets, and prioritizes safety through Human-in-the-Loop (HITL) verification for potentially impactful operations.\n\n## Philosophy\n\n*   **Safety First (HITL):** Critical operations like running terminal commands or deleting/overwriting files often require your explicit confirmation. Review and even edit proposed actions before they run.\n*   **Modular \u0026 Extensible:** Easily enable/disable capabilities (Toolsets) like Terminal, File Management, or the experimental Aider Code Editor per chat session or globally. New toolsets can be added by developers.\n*   **Context-Aware:** Organizes interactions into distinct chat sessions, each with its own history, enabled toolsets, and configurations, allowing you to manage different projects or tasks separately.\n*   **Seamless File Editing (Experimental):** Integrates `aider-chat` for sophisticated, AI-driven code and text file manipulation. *Note: This feature is experimental, potentially less intuitive, may not be enabled by default, and requires careful usage.*\n*   **Multi-LLM \u0026 Configurable:** Supports various OpenAI (GPT) and Google AI (Gemini) models for both the main agent and dedicated translation tasks. Configure models, API keys, default toolsets, and language preferences easily.\n*   **Cross-Platform:** Designed to work on Windows, Linux, and macOS, providing OS-specific guidance to the AI for relevant terminal commands.\n*   **Internationalization:** Supports multiple languages for the user interface and includes a feature to automatically generate translations using an LLM.\n\n---\n\n*   [Features](#features)\n*   [Quickstart Guide](#quickstart-guide)\n*   [Installation](#installation)\n*   [Usage (Command Reference)](#usage-command-reference)\n*   [Toolsets](#toolsets)\n*   [Localization](#localization)\n*   [Development \u0026 Contributing](#development--contributing)\n*   [Warning](#warning)\n*   [License](#license)\n\n---\n\n## Features\n\n*   **Modular Toolsets**: Extensible architecture (Terminal, File Manager, AI Code Copilot [Aider, Experimental], Cognitive).\n*   **Safe Terminal Interaction (HITL)**: Execute shell commands and Python snippets after user review and optional editing/confirmation.\n*   **Safe File Management (HITL)**: Create, read, delete, copy, move, rename files/directories. Destructive/modifying actions require user confirmation. Includes file history and backup/restore for edits (overwrite, find/replace).\n*   **AI-Powered File Editing (Aider, Experimental)**: Integrates `aider-chat` for complex, multi-file code editing. *Use with caution.*\n*   **Cognitive Tools**: Internal tools (`analyse`, `plan`) for the agent to improve reasoning and task breakdown before execution.\n*   **Multi-LLM Support**: Choose from compatible OpenAI (e.g., `gpt-4o`, `gpt-4o-mini`) or Google AI (e.g., `gemini-1.5-pro`) models.\n*   **Separate Translation Model**: Configure a specific LLM for UI localization tasks.\n*   **System-Aware Prompting**: Detects OS (Windows, Linux, macOS) and provides relevant Terminal context to the AI.\n*   **Persistent Chat Management**: Create, load, rename, list, delete distinct chat sessions.\n*   **Per-Chat Toolset Selection**: Activate specific toolsets for different tasks or projects, overriding global defaults.\n*   **Global \u0026 Per-Chat Configuration**: Set application defaults and manage toolset-specific settings (e.g., Aider models, File Manager history limit).\n*   **Secure API Key Management**: Stores keys in `.env` in the project root; prompts securely when needed.\n*   **Multi-Language UI**: Select application language interactively.\n*   **Automated Localization**: Command (`--localize`) to generate UI translations for new languages using an LLM.\n*   **Message Editing**: Correct your last *human* message and resend (`--edit last \"...\"`).\n*   **Temporary Chats**: Quick, disposable chat sessions that can be easily flushed (`-tc`, `--temp-flush`).\n*   **Direct Command Execution**: Option to bypass AI/HITL for immediate command execution (`-x`, `--execute`).\n\n---\n\n## Quickstart Guide\n\n### 1. First-Time Setup\n\nRun `ai` in your terminal for the first time. You'll be guided through a setup wizard:\n\n1.  **Select Language**: Choose the UI language (requires restart if changed).\n    ```console\n    SYSTEM: Please select the application language:\n      1: en \u003c- Current\n      2: pl # Example - other languages may appear if localized\n    Enter number (1-2) or leave empty to keep 'en'\u003e : [CURSOR]\n    ```\n2.  **Select Default AI Model**: Choose the main LLM for the agent (e.g., `gpt-4o-mini`).\n    ```console\n    SYSTEM: Please select the ai-shell-agent llm model from the available:\n    SYSTEM: OpenAI:\n    - gpt-4o (aliases: 4o)\n    - gpt-4o-mini (aliases: 4o-mini) \u003c- Current Model\n    SYSTEM: Google:\n    - gemini-1.5-pro\n    Please input the model you want to use, or leave empty to keep using 'gpt-4o-mini'\n    \u003e : [CURSOR]\n    ```\n3.  **Provide API Key**: Enter the API key for the chosen model's provider (e.g., OpenAI API Key). It will be securely saved to a `.env` file in the agent's installation directory.\n    ```console\n    SYSTEM: Configuration required: Missing environment variable 'OPENAI_API_KEY'.\n    INFO: Description: OpenAI API Key (used if GPT models are selected for Aider)\n    Please enter the value for OPENAI_API_KEY: ****[INPUT HIDDEN]****\n    INFO: Value for 'OPENAI_API_KEY' saved.\n    ```\n4.  **Select Default Enabled Toolsets**: Choose which toolsets are active by default when you create *new* chats (e.g., Terminal, File Manager, Cognitive). Aider is available but likely not included in the defaults due to its experimental nature.\n    ```console\n    SYSTEM: Please select the default enabled toolsets.\n    These toolsets will be enabled by default when you create new chats.\n    SYSTEM: Available Toolsets:\n      1: AI Code Copilot **EXPERIMENTAL** - Provides tools for interacting with the AI Code Copilot for editing code and scripts.\n      2: Cognitive                    - Provides internal tools for agent analysis and planning.\n      3: File Manager                 - Provides tools for direct file and directory manipulation (create, read, edit, delete, copy, move, find, history).\n      4: Terminal                     - Provides tools to execute shell commands and Python code.\n    Enter comma-separated numbers TO ENABLE by default (e.g., 1,3).\n    To disable all - enter 'none'.\n    Leave empty to use the current defaults: Cognitive, File Manager, Terminal. # Example default\n\n    \u003e : 2,3,4 [CURSOR] # Example: Enabling Cognitive, Files, Terminal\n    ```\n\n### 2. Basic Interaction\n\n*   **Start a new chat or talk in the current one:**\n    ```bash\n    # Start a new chat session named \"my-project\" (or load if exists)\n    ai -c \"my-project\"\n\n    # Ask a question or give an instruction within the current chat\n    ai \"What files are in the current directory?\"\n    ```\n    The AI will analyze your request. If it needs to run a command (like `ls` or `dir`), it will propose it using the **Terminal** toolset (if enabled).\n\n*   **Human-in-the-Loop (HITL) Example (Terminal):**\n    ```bash\n    ai \"Show current path\"\n    ```\n    *(Agent's interaction might look like this)*\n    ```console\n    AI: Used tool 'terminal_usage_guide'\n    AI: ⏳ Thinking...\n    SYSTEM:  AI wants to perform an action 'run_terminal_command', edit or confirm command: pwd\n    (edit or confirm command) \u003e : pwd [CURSOR_IS_HERE]\n    ```\n    *   Press **Enter** to confirm the command `pwd`.\n    *   **Edit** the command if needed (e.g., change to `ls -l`), then press Enter.\n    *   Press **Ctrl+C** to cancel the action.\n\n    *(If confirmed, the agent executes the command and responds)*\n    ```console\n    AI: Used tool 'run_terminal_command' with cmd: 'pwd'\n    TOOL: (run_terminal_command) Executed: `pwd`\\nOutput:\\n---\\n/home/user/your_project\\n---\n    AI: ⏳ Thinking...\n    AI: The current path is /home/user/your_project.\n    ```\n\n### 3. Using Toolsets (Examples)\n\n*   **File Manager:**\n    ```bash\n    # Create a file (no confirmation needed)\n    ai \"Create a file named notes.md with the content 'Initial thoughts.'\"\n\n    # Delete a file (requires confirmation)\n    ai \"Delete the file old_notes.txt\"\n    ```\n    *(Agent's interaction)*\n    ```console\n    AI: Used tool 'file_manager_usage_guide'\n    AI: ⏳ Thinking...\n    SYSTEM: AI wants to perform action 'delete_file_or_dir'.\n    Delete file: '/path/to/your/project/old_notes.txt'?\n    (confirm: yes/no) \u003e : [CURSOR]\n    ```\n    *   Type `yes` and press Enter to confirm deletion.\n\n*   **AI Code Copilot (Aider, Experimental):**\n    *Note: This toolset might need to be manually enabled (`ai --select-tools`) and configured (`ai --configure-toolset ...`). Its HITL flow is more complex and less polished.*\n    ```bash\n    # Start a chat specific to coding task\n    ai -c \"fix-bug-123\"\n    # (Ensure Aider toolset is enabled for this chat)\n    ai --select-tools # Select \"AI Code Copilot **EXPERIMENTAL**\" if needed\n\n    # Add files to Aider's context\n    ai \"Add main.py to the code editor context\"\n    # AI uses 'add_file_to_copilot_context'\n\n    # Request a simple edit\n    ai \"In main.py, add a print statement 'Starting...' at the beginning of the main function.\"\n    # AI uses 'request_copilot_edit'\n    # Aider starts working. It might ask for clarification:\n    ```\n    *(Agent's interaction)*\n    ```console\n    AI: Used tool 'aider_usage_guide'\n    AI: ⏳ Thinking...\n    AI: [CODE_COPILOT_INPUT_REQUEST] AI Code Copilot requires input. Please respond using 'respond_to_code_copilot_input_request'. Prompt: 'Apply the changes? (yes/no/details)' Options: (yes/no/all/skip/don't ask)\n    ```\n    ```bash\n    # Respond to Aider's prompt (requires confirmation of YOUR response)\n    ai \"Respond to the code copilot: yes\"\n    ```\n    *(Agent's interaction)*\n    ```console\n    AI: ⏳ Thinking...\n    SYSTEM:  AI wants to perform an action 'respond_to_code_copilot_input_request', edit or confirm response: yes\n    (edit or confirm response) \u003e : yes [CURSOR] # Press Enter\n    ```\n    *(Aider continues with the confirmed input. It might finish or ask again.)*\n\n    ```bash\n    # View the changes made by Aider\n    ai \"Show the diff of the changes made\"\n    # AI uses 'view_code_copilot_edit_diffs'\n\n    # Close the Aider session when done\n    ai \"Close the code copilot\"\n    ```\n\n### 4. Configuration \u0026 Management\n\n*   **Change Main AI Model:** `ai --select-model`\n*   **Change Translation Model:** `ai --select-translation-model`\n*   **Update API Key (for current main model):** `ai -k` or `ai --set-api-key`\n*   **List Available Toolsets \u0026 Status:** `ai --list-toolsets`\n*   **Change Enabled Toolsets (Current Chat/Global):** `ai --select-tools`\n*   **Configure Specific Toolset Settings:** `ai --configure-toolset \"File Manager\"` (Use the exact name from `--list-toolsets`)\n*   **List Chat History:** `ai --list-messages`\n*   **Edit Last Message:** `ai --edit last \"My corrected message\"`\n*   **Execute Command Directly (Bypass AI/HITL):** `ai -x \"git status\"`\n\n---\n\n## Installation\n\nRequires **Python 3.11+**.\n\n```bash\npip install ai-shell-agent\n```\n*(Note: If you encounter issues related to specific toolsets like Aider, you might need to ensure its dependencies are met separately. Refer to the `aider-chat` documentation if necessary.)*\n\n---\n\n## Usage (Command Reference)\n\n```\nai [OPTIONS] [MESSAGE]\n```\n\n**Main Interaction:**\n\n*   `[MESSAGE]`: The message/prompt/instruction to send to the AI agent (if no other command is given).\n*   `-m, --send-message \"MSG\"`: Explicitly send a message to the current chat.\n*   `-tc, --temp-chat \"MSG\"`: Start a temporary chat session with the message.\n*   `-e, --edit IDX|\"last\" \"MSG\"`: Edit message `IDX` (integer) or the `last` human message and resend.\n*   `-x, --execute \"CMD\"`: Execute the shell command `CMD` directly using the Terminal tool's backend (no AI/HITL). Output is added to chat history.\n*   `-lsm, --list-messages`: Show the history of the current chat.\n\n**Chat Management:**\n\n*   `-c, --chat TITLE`: Create a new chat session with `TITLE` or load an existing one. Sets it as the current chat.\n*   `-lc, --load-chat TITLE`: Same as `-c`.\n*   `-lsc, --list-chats`: List all available chat session titles.\n*   `-rnc, --rename-chat OLD_TITLE NEW_TITLE`: Rename a chat session.\n*   `-delc, --delete-chat TITLE`: Delete a chat session and its history.\n*   `--temp-flush`: Delete all chats whose titles start with \"Temp Chat \".\n*   `-ct, --current-chat-title`: Print the title of the currently active chat.\n\n**Model \u0026 Language Configuration:**\n\n*   `-llm, --model MODEL_NAME`: Set the main agent LLM (e.g., `gpt-4o-mini`, `gemini-1.5-pro`). Prompts for API key if needed for the new model.\n*   `--select-model`: Interactively select the main agent LLM from a list.\n*   `-k, --set-api-key [API_KEY]`: Set/update the API key for the *currently configured* main agent model. Prompts if `API_KEY` is omitted.\n*   `--select-translation-model`: Interactively select the LLM used for the `--localize` command.\n*   `--select-language`: Interactively select the application's display language.\n\n**Toolset Management:**\n\n*   `--list-toolsets`: List available toolsets and their enabled status (global or for the current chat).\n*   `--select-tools`: Interactively enable/disable toolsets (globally if no chat active, otherwise for the current chat *and* updates global defaults).\n*   `--configure-toolset TOOLSET_NAME`: Run the interactive configuration wizard for a specific toolset (use the exact name from `--list-toolsets`). Affects global defaults or the current chat's settings.\n\n**Utilities:**\n\n*   `--localize LANGUAGE_NAME`: Generate localized UI text files for the target language (e.g., `\"Polish\"`, `\"Spanish\"`, `\"Pirate Speak\"`). The name provided is used in the filename (e.g., `polish_texts.json`). Uses the configured translation model.\n\n---\n\n## Toolsets\n\nToolsets provide the agent's capabilities. They can be managed per-chat or globally.\n\n**Available Toolsets (Default enabled toolsets may vary based on setup):**\n\n*   **`Terminal`**: Allows execution of shell commands and Python code snippets. Uses HITL for safety. Provides OS-specific context to the AI.\n*   **`File Manager`**: Enables direct file system operations (create, read, delete, copy, move, rename, find). Uses HITL for destructive/modifying actions. Includes file history and backup/restore features.\n*   **`AI Code Copilot **EXPERIMENTAL**`**: (May not be enabled by default) Integrates `aider-chat` for advanced, context-aware file editing and creation within a persistent session. Uses a specialized, complex HITL workflow. *Use with caution and expect potential usability issues.*\n*   **`Cognitive`**: Provides internal tools (`analyse`, `plan`) for the agent to improve its reasoning and planning before taking action. Outputs are internal notes, not shown directly to the user.\n\n**Managing Toolsets:**\n\n*   Use `ai --list-toolsets` to see available and enabled toolsets.\n*   Use `ai --select-tools` to enable/disable toolsets for the current chat (if active) or globally.\n*   Use `ai --configure-toolset \"Toolset Name\"` to adjust settings specific to a toolset (like Aider's models).\n\n---\n\n## Localization\n\nThe AI Shell Agent interface can be displayed in multiple languages.\n\n*   **Selecting Language:** Use `ai --select-language` for an interactive prompt. A restart is required after changing the language.\n*   **Generating Translations:** For developers or users wanting to add/update translations:\n    1.  Ensure the desired translation LLM model is selected (`ai --select-translation-model`).\n    2.  Ensure the API key for the translation model provider is set in `.env`.\n    3.  Run `ai --localize \"LANGUAGE_NAME\"` (e.g., `ai --localize \"Polish\"`, `ai --localize \"Pirate Speak\"`). The name provided dictates the generated filename (e.g., `polish_texts.json`, `pirate speak_texts.json`).\n    4.  This will find all `en_texts.json` files (in the core agent and toolsets), translate their string values using the LLM, and save new `\u003clanguage_name\u003e_texts.json` files. Tool names and other specific keys are excluded from translation.\n\n---\n\n## Development \u0026 Contributing\n\n*   **Structure:** The agent is built with Python, leveraging libraries like `langchain`, `rich`, and `prompt_toolkit`. Toolsets are located in `ai_shell_agent/toolsets/`. Core logic is in `ai.py`, `chat_manager.py`, `llm.py`. State is managed via `config_manager.py` and `chat_state_manager.py`. UI via `console_manager.py`.\n*   **Adding Toolsets:** Follow the detailed guide: [How to Add a New Toolset](how_to_add_toolsets.md)\n*   **Dependencies:** Install development dependencies if contributing: `pip install -r requirements-dev.txt` (if available).\n\n---\n\n## Warning\n\nThis tool interacts directly with your system (terminal, file system). While safety measures like Human-in-the-Loop (HITL) confirmation are implemented for many actions, **always review proposed commands and file operations carefully before confirming.** The developers are not responsible for any data loss or system damage caused by misuse or unexpected behavior. Use at your own risk, especially the **experimental** AI Code Copilot (Aider) integration which may have rough edges and a complex interaction model.\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See the `LICENSE` file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaelhalawani%2Fai-shell-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaelhalawani%2Fai-shell-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaelhalawani%2Fai-shell-agent/lists"}