ai-shell-agent 0.1.6

A command-line AI chat application that helps perform tasks by writing and executing terminal commands with user supervision and by answering questions.

AI Shell Agent

AI Shell Agent is a command-line LLM-powered tool that can help you perform tasks by writing and executing terminal commands (with human confirmation or edit) and responding to questions, directly from the console.
It features a very simple CLI and adjusts the LLM prompts based on your detected system.
Works on Windows, Linux with Bash, and Mac. (Tested on Windows, please contribute!)

Installation

pip install ai-shell-agent

This will automatically install the CLI tool in your current Python environment.
Requires python=3.11.x.
You can also clone and install from the repository.

Please make sure your python scripts are added to path correctly.

Quickly send messages

ai "your message here"

This will send a message to the AI in the active chat (and create a new chat if there isn't one active).

https://github.com/user-attachments/assets/6df08410-37e5-4e21-b99c-4133c15192cc

You will see the AI response or editable commands that the AI wants to run, which you can confirm by pressing Enter.

Output of the command is displayed in the console and added to the chat messages.
Once all the commands are run, the AI will provide its interpretation of the results or try to run more commands.

If you haven't set your API key yet, you will be prompted.

Execute command yourself and ask about the outputs

https://github.com/user-attachments/assets/982fcf59-7b9c-4e04-93f9-041fbc819ccb

ai -x "dir"

This will execute the command and add the output to the AI logs, as it can't see the whole console.

ai "tell me about these files"

Will present both the command output and the question to the AI.

You can run multiple commands in a row and then ask your question too.
Or even run a few commands yourself and then ask the AI to finish up.

Titled chats

ai -c "title of new or existing chat"
ai "your message here"

Will create a new chat and set it active if it doesn't exist, then send a message to the active chat.

Temporary chats

ai -tc "your first message in a temporary chat"

Will create a new temporary chat without a title and set it active.

Edit last message

ai -e "updated last message"

Will update the last message and send the updated chat to the llm to reply. You can also specify the user message id you want to update. It's displayed after each message you send, and when you list messages with ai -lsm.

https://github.com/user-attachments/assets/02eb3824-933c-4d97-b4ac-23d240a62085

Multistep execution and debugging

When you ask AI to do something for you it will try to run commands, observe results and act. This is typical ReACT agent behaviour. It can fix errors and debug until it gets the task done.

https://github.com/user-attachments/assets/049e6e37-5a5d-4125-b891-e1bb1f2ecdbf

---

Table of Contents

• Features
• Warning
• Quickstart Guide
• Installation
• Usage
• Development & Contributing
• Acknowledgements
• License

---

Warning

Please use at your own risk. AI can still generate wrong and possibly destructive commands. You always can view the command before sending—please be mindful. If you see any dangerous commands, please post a screenshot.

---

Features

• Chat Session Management:
  Create new chats or load existing ones using a title, have one active chat session set to receive messages by default.

• API Key Management:
  Set and update your OpenAI API key via a dedicated command. You will be prompted to input the key if you have not provided it yet.

• Message Handling:
  Send new messages or edit previous ones within an active session with the simple ai "your message" command.

• Temporary Sessions:
  Start temporary sessions for quick, ephemeral chats (currently saved as temp chats under UUID names for easier debugging and tracing).

• Shell Command Execution:
  The LLM can write your commands, and you can edit them or execute them with one press of a button.

• Python Code Execution:
  The agent also has the ability to run Python REPL, though this feature hasn't undergone extensive development or testing.

---

Quickstart Guide

Setting Up the API Key

Upon launching AI Shell Agent for the first time, if no API key is detected, the application will prompt you to enter it:

$ ai "Hi"
No OpenAI API key found. Please enter your OpenAI API key:

After entering the key, it will be saved in a .env file located in the project's installation directory. This ensures that your API key is securely stored and automatically loaded in future sessions.

Managing the API Key

If you need to update or set a new API key at any time, use the following command:

ai -k

Shorthand:

ai -k

Starting a Chat Session

Create a new chat session with a title:

ai -c "My Chat Session"

Shorthand:

ai -c "My Chat Session"

Sending a Message

To send a message to the active chat session:

ai "what is the time right now?"

Executing Shell Commands

Run a shell command directly:

ai -x "dir"

Shorthand:

ai -x "dir"

By automatically detecting your operating system (via Python’s platform library), AI Shell Agent customizes its console suggestions for Windows CMD, Linux bash, or macOS Terminal.

Temporary Chat Sessions

Start a temporary session (untitled, currently saved to file but untitled):

ai -tc "Initial temporary message"

Shorthand:

ai -tc "Initial temporary message"

Listing and Managing Sessions

• List Sessions:

  ai -lsc
  

  Shorthand:

  ai -lsc
  

• Load an Existing Session:

  ai -lc "My Chat Session"
  

  Shorthand:

  ai -lc "My Chat Session"
  

• Rename a Session:

  ai -rnc "Old Title" "New Title"
  

  Shorthand:

  ai -rnc "Old Title" "New Title"
  

• Delete a Session:

  ai -delc "Chat Title"
  

  Shorthand:

  ai -delc "Chat Title"
  

• List messages:

  ai -lsm
  

  Shorthand:

  ai -lsm
  

• Show the current chat title:

  ai -ct
  

  Shorthand:

  ai -ct
  

---

Installation

Installing from PyPI

pip install ai-shell-agent

Installing from Source

1. Clone the repository:

   git clone https://github.com/laelhalawani/ai-shell-agent.git
   

2. Navigate to the project directory:

   cd ai-shell-agent
   

3. Install the package:

   pip install .
   

---

Usage

API Key Management

• Set or Update API Key:

  ai -k
  

  Shorthand:

  ai -k
  

Chat Session Management

• Create or Load a Chat Session:

  ai -c "Session Title"
  

  Shorthand:

  ai -c "Session Title"
  

Messaging

• Send a Message:

  ai -m "Your message"
  

  Shorthand:

  ai -m "Your message"
  

• Edit a Message at a Given Index:

  ai -e 1 "Updated message"
  

  Shorthand:

  ai -e 1 "Updated message"
  

System Prompt Management

• Set Default System Prompt:

  ai --default-system-prompt "Your default system prompt"
  

Shell Command Execution

• Direct Execution (without confirmation):

  ai -x "your shell command"
  

  Shorthand:

  ai -x "your shell command"
  

---

Development & Contributing

Follow the same steps as described earlier.

---

License

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