SmartCLI - AI-Powered Command Line Assistant

A truly autonomous AI assistant for your terminal. Like ChatGPT, but for command-line operations.

✨ Features

• 🤖 Autonomous AI Agent - AI can gather information and make decisions
• 💬 Conversational Interface - Chat naturally with your CLI
• 🔧 Execute Commands - AI can run shell commands with your permission
• 📊 Gather Information - AI automatically gets the info it needs
• 🎨 Beautiful UI - Clean, colorful output
• 🔒 Safe - Always asks for confirmation before executing

🚀 Quick Start

Installation

# 1. Clone or download the project
cd smartcli

# 2. Install dependencies
npm install

# 3. Set your OpenAI API key
export OPENAI_API_KEY="sk-your-key-here"

# 4. Build
npm run build

# 5. Link globally (optional)
npm link

# 6. Run!
smartcli

Usage

Interactive Mode:

smartcli

One-Shot Commands:

smartcli create a folder named notes
smartcli generate a commit message
smartcli explain recursion

💡 How It Works

The AI has three modes of operation:

1. Execute Commands

When you ask it to do something:

You: Create a file named app.js with hello world

AI: I'll create a file with console.log
┌─ Command:
│ echo 'console.log("Hello World");' > app.js
└─
? Execute this command? Yes
✓ Done

2. Gather Information

When AI needs data, it automatically gathers it:

You: Generate a commit message

AI: I'll check your staged changes first.
🤖 AI gathering information...
  ⚙️  git diff --cached --name-only
  ✓ Done
  ⚙️  git diff --cached
  ✓ Done
  🧠 Processing information...

AI: Based on your changes, I suggest:
"feat: add user authentication module

- Implement login functionality
- Add JWT token handling"

Would you like me to commit with this message?

3. Explain Concepts

For questions and explanations:

You: Explain recursion

AI: Recursion is a programming technique where a function calls
itself to solve a problem. It consists of two parts:

1. Base case: The condition that stops recursion
2. Recursive case: The function calling itself

Example:
function factorial(n) {
  if (n === 0) return 1;  // base case
  return n * factorial(n - 1);  // recursive case
}

🎯 Example Use Cases

File Operations

smartcli create a folder structure for a react project
smartcli find all javascript files larger than 100kb
smartcli backup all my config files

Git Operations

smartcli generate a commit message
smartcli show me what changed in the last commit
smartcli create a new branch called feature-auth

Information Gathering

smartcli what's taking up disk space
smartcli show me all running node processes
smartcli check if port 3000 is available

Code Analysis

smartcli count lines of code in my project
smartcli find all TODO comments
smartcli check for console.log statements

Learning

smartcli explain docker containers
smartcli what is a closure in javascript
smartcli how does git rebase work

🔧 How AI Works

The AI uses special markers to communicate its intentions:

Execute Block

```execute
mkdir notes

AI uses this when it wants to run a command that modifies something.

### Gather Block
```markdown
```gather
git status

AI uses this to silently get information it needs.

You'll see the AI's reasoning and can approve or deny any execution.

## 🏗️ Architecture

User Input ↓ AI Agent (GPT-4) ↓ ┌─────────────┬─────────────┬──────────────┐ │ Gather │ Execute │ Respond │ │ (silent) │ (confirmed) │ (direct) │ └─────────────┴─────────────┴──────────────┘ ↓ Result to User

The AI can:
1. Run commands to gather info (automatically)
2. Execute commands with user approval
3. Respond with explanations (no commands)

## 📁 Project Structure

smartcli/ ├── src/ │ ├── index.ts # Main entry point │ ├── ai-agent.ts # AI logic │ └── ui.ts # Display utilities ├── package.json ├── tsconfig.json └── README.md

**That's it!** Simple, clean architecture.

## 🎨 UI Examples

### Welcome Screen

╔════════════════════════════════════════════╗ ║ SmartCLI - AI Assistant ║ ╚════════════════════════════════════════════╝

An intelligent CLI powered by GPT-4 Ask me anything or tell me what to do!

### AI Response

🤖 AI: I'll create that folder for you.

┌─ Command: │ mkdir notes └─

? Execute this command? Yes ✓ Done

### Information Gathering

🤖 AI gathering information... ⚙️ git diff --cached --name-only ✓ Done ⚙️ git diff --cached ✓ Done 🧠 Processing information...

🤖 AI: Based on your changes...

## ⚙️ Configuration

### Environment Variables

Create `.env` file:
```bash
OPENAI_API_KEY=sk-your-key-here

Or export:

export OPENAI_API_KEY="sk-your-key-here"

Make it permanent (add to ~/.zshrc or ~/.bashrc):

echo 'export OPENAI_API_KEY="sk-your-key-here"' >> ~/.zshrc
source ~/.zshrc

🧪 Testing

Try these commands to test functionality:

# Simple command
smartcli create a test file

# Needs information gathering
smartcli generate a commit message

# Pure explanation
smartcli explain promises in javascript

# Complex operation
smartcli find and list all large files

# Interactive conversation
smartcli
> create a new project structure
> what files do I have
> explain the last command
> exit

🐛 Troubleshooting

"OPENAI_API_KEY not found"

export OPENAI_API_KEY="sk-your-key"

"command not found: smartcli"

npm link
# or run directly:
npm run dev

TypeScript errors

rm -rf node_modules dist
npm install
npm run build

🎓 Tips

1. Be conversational - "Create a folder named notes" or just "make a notes folder"
2. Ask questions - AI will gather info it needs automatically
3. Multi-step operations - AI can handle complex workflows
4. Review before executing - Always check what AI wants to run
5. Iterate - If something doesn't work, just ask AI to fix it

🔐 Security

• AI always asks before executing commands
• You can see exactly what will run
• No commands are hidden
• Uses bash for execution (same as your terminal)

📝 Development

# Development mode
npm run dev

# Build
npm run build

# Watch mode
npm run watch

🤝 Contributing

This is a simple, clean codebase. Feel free to:

• Add features
• Improve AI prompts
• Enhance UI
• Fix bugs

📜 License

MIT

🙏 Acknowledgments

• OpenAI for GPT-4
• The Node.js community

---

Built with ❤️ for developers who want AI assistance in their terminal