@profullstack/ai

A powerful AI agent CLI tool for interactive conversations with AI, featuring file operations and command execution capabilities.

Installation

``bash
npm install -g @profullstack/ai
`

Or using pnpm:

`bash
pnpm add -g @profullstack/ai
`

Features

- 🤖 Interactive AI Chat: Conversational interface with AI models
- 📁 File Operations: Read, write, and delete files with permission prompts
- ⚡ Command Execution: Run system commands safely with user approval
- 🔐 Permission System: Granular control with "allow", "disallow", "allow forever" options
- 🔑 Multi-Provider Support: Works with OpenAI GPT and Anthropic Claude models
- ⚙️ Flexible Configuration: Customizable settings and API key management
- 📊 Conversation History: Track and export chat sessions

Usage

$3

The AI agent runs in enhanced mode by default, which enables file operations and command execution:

`bash
ai
`

This starts an interactive session where the AI can:
- Read and analyze files in your project
- Create, modify, and delete files (with your permission)
- Execute commands like npm install, git status, etc.
- List directory contents and check file existence

Security: You'll be prompted before any file or command operation with options:
- Allow (this time only)
- Disallow (reject the action)
- Allow forever (permanently allow this type of action)

$3

To use the traditional text-only mode without file/command capabilities:

`bash
ai --no-enhanced
`

$3

Simply run ai to start an interactive chat session:

`bash
ai
`

This will start an interactive prompt where you can have conversations with the AI:

`
🤖 AI Agent
Type your questions or commands. Type "exit" or "quit" to leave.

ai > Hello, how are you?
🤖 Hello! I'm your AI assistant. How can I help you today?

ai > What can you do?
🤖 I can help you with a wide variety of tasks including:
• Answering questions on various topics
• Helping with writing and editing
• Explaining concepts and ideas
• Providing suggestions and recommendations
• Assisting with problem-solving
• And much more! Just ask me anything you'd like help with.

ai > exit
Goodbye! 👋
`

$3

Ask a single question and get a response:

`bash
ai ask "What is the capital of France?"
`

$3

- help or ? - Show help message
- clear - Clear conversation history
- config - Show current configuration
- exit, quit, or q - Exit the AI agent

$3

Control what actions the AI can perform:

`bash


Show current permissions

ai config --show-permissions

Reset all permissions (will prompt again for each action)

ai config --reset-permissions
`

Permission Types:
- file_read - Reading files
- file_write - Writing/creating files
- file_delete - Deleting files
- command_exec - Executing system commands

Permission Levels:
- Allow (this time only) - Permit the action once
- Disallow - Reject the action
- Allow forever - Permanently allow this action type
- [x] Auto-approve - Automatically allow approved actions (for commands in approved list)

$3

Control which commands can be auto-approved:

`bash


Show approved commands list

ai config --show-commands

Add a command to approved list

ai config --add-command "git status"

Remove a command from approved list

ai config --remove-command "rm -rf"

Reset to default approved commands

ai config --reset-commands
`

Default Approved Commands:
Safe, read-only commands like ls, pwd, git status, npm list, etc. are pre-approved for auto-execution when auto-approve mode is enabled.

Quick Setup

For first-time setup, use the interactive setup command:

`bash
ai setup
`

This will guide you through:
- Setting up OpenAI and/or Anthropic API keys
- Choosing your preferred AI model
- Configuring response settings

Configuration

$3

`bash
ai config --show
`

$3

`bash
ai config --set model=gpt-4
ai config --set temperature=0.8
ai config --set maxTokens=2000
`

$3

`bash


Interactive setup (recommended)

ai setup

Manual API key setup

ai config --set-openai-key sk-your-openai-key-here
ai config --set-anthropic-key sk-ant-your-anthropic-key-here

Check API key status

ai config --show-keys
`

API keys are stored securely in ~/.config/ai/config.json and can also be set via environment variables:

`bash
export OPENAI_API_KEY=sk-your-openai-key-here
export ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here
`

$3

`bash
ai config --reset
`

$3

`bash


Export configuration to a file

ai config --export my-config.json

Import configuration from a file

ai config --import my-config.json
`

$3

Export all your AI agent data (configuration, API keys, conversation history) to a zip file:

`bash
ai export
`

This creates ~/ai-agent.zip containing:
- Configuration settings (model, temperature, etc.)
- API keys (OpenAI, Anthropic)
- All conversation history

To restore on another machine:
`bash


Copy the zip file to the target machine, then:


unzip ~/ai-agent.zip -d ~
`

Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| model | string | gpt-3.5-turbo | AI model to use |
| temperature | number | 0.7 | Response creativity (0.0-2.0) |
| maxTokens | number | 1000 | Maximum response length |
| systemPrompt | string | You are a helpful AI assistant. | System prompt |
| verbose | boolean | false | Enable verbose output |
| openaiApiKey | string | null | OpenAI API key for GPT models |
| anthropicApiKey | string | null | Anthropic API key for Claude models |
| apiEndpoint | string | null | Custom API endpoint |

Command Line Options

$3

`bash
ai chat [options]
`

Options:
- -m, --model - AI model to use
- -t, --temperature - Response creativity (0.0-2.0)
- --max-tokens - Maximum response length
- --system - System prompt to use
- --verbose - Enable verbose output

$3

`bash
ai ask [options]
`

Same options as interactive mode.

Examples

$3

`javascript
import { EnhancedAIAgent } from '@profullstack/ai';

const agent = new EnhancedAIAgent({
model: 'gpt-3.5-turbo',
temperature: 0.7
});

// AI can now read files, write files, and execute commands
const response = await agent.query('Read my package.json and create a simple README for this project');
console.log(response);
`

$3

`javascript
import { AIAgent } from '@profullstack/ai';

const agent = new AIAgent({
model: 'gpt-3.5-turbo',
temperature: 0.7
});

const response = await agent.query('Hello, world!');
console.log(response);
`

$3

`javascript
import { readFile, writeFile, executeCommand } from '@profullstack/ai';

// These functions include built-in permission prompts
const content = await readFile('./myfile.txt');
await writeFile('./output.txt', 'Hello, world!');
const result = await executeCommand('npm test');
`

$3

`javascript
import { getConfig, updateConfig, setOpenAIKey, getOpenAIKey } from '@profullstack/ai';

// Get current configuration
const config = getConfig();
console.log(config);

// Update configuration
updateConfig('temperature', 0.8);
updateConfig('model', 'gpt-4');

// Set API keys
setOpenAIKey('sk-your-openai-key-here');
setAnthropicKey('sk-ant-your-anthropic-key-here');

// Get API keys
const openaiKey = getOpenAIKey(); // Checks env var first, then config file
const anthropicKey = getAnthropicKey();
`

$3

`javascript
import { AIAgent } from '@profullstack/ai';

const agent = new AIAgent();

await agent.query('Hello!');
await agent.query('How are you?');

// Get conversation stats
const stats = agent.getStats();
console.log(stats);

// Export history
const history = agent.exportHistory('markdown');
console.log(history);

// Clear history
agent.clearHistory();
`

Development

$3

`bash
git clone https://github.com/profullstack/ai.git
cd ai
pnpm install
`

$3

`bash
pnpm run example
`

$3

`bash
pnpm run cli
`

API Reference

$3

The enhanced agent extends AIAgent with file and command capabilities.

#### Constructor

`javascript
new EnhancedAIAgent(options)
`

Options:
- model - AI model to use
- temperature - Response creativity
- maxTokens - Maximum response length
- system - System prompt
- verbose - Enable verbose output
- enableActions - Enable file/command operations (default: true)

#### Methods

- query(message) - Send a message and get a response (with action processing)
- clearHistory() - Clear conversation history
- getHistory() - Get conversation history
- getStats() - Get conversation statistics
- exportHistory(format) - Export history in specified format
- setActionsEnabled(enabled) - Enable/disable action processing
- getActionsEnabled() - Check if actions are enabled

$3

Basic text-only agent without file/command capabilities.

#### Constructor

`javascript
new AIAgent(options)
`

Options:
- model - AI model to use
- temperature - Response creativity
- maxTokens - Maximum response length
- system - System prompt
- verbose - Enable verbose output

#### Methods

- query(message) - Send a message and get a response
- clearHistory() - Clear conversation history
- getHistory() - Get conversation history
- getStats() - Get conversation statistics
- exportHistory(format) - Export history in specified format

$3

- getConfig() - Get current configuration
- updateConfig(key, value) - Update configuration value
- resetConfig() - Reset to default configuration
- exportConfig(filePath) - Export configuration to file
- importConfig(filePath) - Import configuration from file
- validateConfig(config) - Validate configuration
- getAvailableModels() - Get list of available models
- getConfigSchema() - Get configuration schema


$3

File and command operations with built-in permission prompts:

- readFile(filePath) - Read a file with permission check
- writeFile(filePath, content) - Write to a file with permission check
- deleteFile(filePath) - Delete a file with permission check
- executeCommand(command, options) - Execute a command with permission check
- listFiles(dirPath) - List files in a directory
- fileExists(filePath) - Check if a file exists

$3

- resetPermissions() - Reset all action permissions
- showPermissions() - Display current permission settings
- ACTION_TYPES - Constants for action types
- PERMISSION_LEVELS - Constants for permission levels

$3

- getOpenAIKey() - Get OpenAI API key (env var or config file)
- setOpenAIKey(key) - Set OpenAI API key in config file
- getAnthropicKey() - Get Anthropic API key (env var or config file)
- setAnthropicKey(key)` - Set Anthropic API key in config file

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For support, please open an issue on GitHub or contact us at support@profullstack.com.