{"id":31956347,"url":"https://github.com/profullstack/ai","last_synced_at":"2026-03-13T10:32:50.711Z","repository":{"id":295191043,"uuid":"989416888","full_name":"profullstack/ai","owner":"profullstack","description":"An npm CLI for interacting with AI agents from the shell.","archived":false,"fork":false,"pushed_at":"2025-06-15T13:22:58.000Z","size":65,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-23T19:57:19.134Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/profullstack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-24T04:00:48.000Z","updated_at":"2025-06-15T13:23:00.000Z","dependencies_parsed_at":"2025-05-24T05:51:27.298Z","dependency_job_id":"8ab58075-c5a2-42af-b6ad-030a84ab2c78","html_url":"https://github.com/profullstack/ai","commit_stats":null,"previous_names":["profullstack/ai"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/profullstack/ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profullstack%2Fai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profullstack%2Fai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profullstack%2Fai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profullstack%2Fai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/profullstack","download_url":"https://codeload.github.com/profullstack/ai/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profullstack%2Fai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30465427,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T06:34:02.089Z","status":"ssl_error","status_checked_at":"2026-03-13T06:33:49.182Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2025-10-14T14:48:36.483Z","updated_at":"2026-03-13T10:32:50.681Z","avatar_url":"https://github.com/profullstack.png","language":"JavaScript","readme":"# @profullstack/ai\n\n[![Crypto Payment](https://paybadge.profullstack.com/badge.svg)](https://paybadge.profullstack.com/?tickers=btc%2Ceth%2Csol%2Cusdc)\n\nA powerful AI agent CLI tool for interactive conversations with AI, featuring file operations and command execution capabilities.\n\n## Installation\n\n```bash\nnpm install -g @profullstack/ai\n```\n\nOr using pnpm:\n\n```bash\npnpm add -g @profullstack/ai\n```\n\n## Features\n\n- 🤖 **Interactive AI Chat**: Conversational interface with AI models\n- 📁 **File Operations**: Read, write, and delete files with permission prompts\n- ⚡ **Command Execution**: Run system commands safely with user approval\n- 🔐 **Permission System**: Granular control with \"allow\", \"disallow\", \"allow forever\" options\n- 🔑 **Multi-Provider Support**: Works with OpenAI GPT and Anthropic Claude models\n- ⚙️ **Flexible Configuration**: Customizable settings and API key management\n- 📊 **Conversation History**: Track and export chat sessions\n\n## Usage\n\n### Enhanced Mode (Default)\n\nThe AI agent runs in enhanced mode by default, which enables file operations and command execution:\n\n```bash\nai\n```\n\nThis starts an interactive session where the AI can:\n- Read and analyze files in your project\n- Create, modify, and delete files (with your permission)\n- Execute commands like `npm install`, `git status`, etc.\n- List directory contents and check file existence\n- Apply precise file modifications using diff-based changes\n- Manage permissions and approved commands through chat\n\n**Enhanced Mode Features:**\n- **ACTION Syntax**: The AI uses special `ACTION:READ_FILE:path` syntax to perform operations\n- **Smart Parsing**: Handles backticks and markdown formatting correctly\n- **In-Chat Configuration**: Manage settings directly through conversation\n- **Diff-Based Editing**: Make precise file changes instead of full rewrites\n\n**Security**: Currently auto-allows actions with clear notifications. You can still control behavior through:\n- **Permanent permissions** in config.json (`\"file_read\": \"allow_forever\"`)\n- **Auto-approve + approved commands** for safe command execution\n- **In-chat commands** to manage permissions and approved commands\n\n### Text-Only Mode\n\nTo use the traditional text-only mode without file/command capabilities:\n\n```bash\nai --no-enhanced\n```\n\n### Interactive Mode (Default)\n\nSimply run `ai` to start an interactive chat session:\n\n```bash\nai\n```\n\nThis will start an interactive prompt where you can have conversations with the AI:\n\n```\n🤖 AI Agent\nType your questions or commands. Type \"exit\" or \"quit\" to leave.\n\nai \u003e Hello, how are you?\n🤖 Hello! I'm your AI assistant. How can I help you today?\n\nai \u003e What can you do?\n🤖 I can help you with a wide variety of tasks including:\n• Answering questions on various topics\n• Helping with writing and editing\n• Explaining concepts and ideas\n• Providing suggestions and recommendations\n• Assisting with problem-solving\n• And much more! Just ask me anything you'd like help with.\n\nai \u003e exit\nGoodbye! 👋\n```\n\n### Single Query Mode\n\nAsk a single question and get a response:\n\n```bash\nai ask \"What is the capital of France?\"\n```\n\n### Available Commands in Interactive Mode\n\n- `help` or `?` - Show help message\n- `clear` - Clear conversation history\n- `config` - Show current configuration\n- `exit`, `quit`, or `q` - Exit the AI agent\n\n### In-Chat Configuration Commands\n\nYou can also manage permissions and settings directly through conversation:\n\n```bash\nai \u003e show my current permissions\nai \u003e show my approved commands\nai \u003e approve the command \"docker ps\"\nai \u003e remove the command \"rm -rf\" from approved list\nai \u003e set file operations to auto-approve\nai \u003e reset my permissions\n```\n\nThe AI will understand these natural language commands and execute the appropriate configuration changes.\n\n### Permission Management\n\nControl what actions the AI can perform:\n\n```bash\n# Show current permissions\nai config --show-permissions\n\n# Reset all permissions (will prompt again for each action)\nai config --reset-permissions\n```\n\n**Permission Types:**\n- `file_read` - Reading files\n- `file_write` - Writing/creating files\n- `file_delete` - Deleting files\n- `command_exec` - Executing system commands\n\n**Permission Levels:**\n- **Allow** (this time only) - Permit the action once\n- **Disallow** - Reject the action\n- **Allow forever** - Permanently allow this action type\n- **[x] Auto-approve** - Automatically allow approved actions (for commands in approved list)\n\n### Approved Commands Management\n\nControl which commands can be auto-approved:\n\n```bash\n# Show approved commands list\nai config --show-commands\n\n# Add a command to approved list\nai config --add-command \"git status\"\n\n# Remove a command from approved list\nai config --remove-command \"rm -rf\"\n\n# Reset to default approved commands\nai config --reset-commands\n```\n\n**Default Approved Commands:**\nSafe, read-only commands like `ls`, `pwd`, `git status`, `npm list`, etc. are pre-approved for auto-execution when auto-approve mode is enabled.\n\n## Quick Setup\n\nFor first-time setup, use the interactive setup command:\n\n```bash\nai setup\n```\n\nThis will guide you through:\n- Setting up OpenAI and/or Anthropic API keys\n- Choosing your preferred AI model\n- Configuring response settings\n\n## Configuration\n\n### View Current Configuration\n\n```bash\nai config --show\n```\n\n### Set Configuration Values\n\n```bash\nai config --set model=gpt-4\nai config --set temperature=0.8\nai config --set maxTokens=2000\n```\n\n### API Key Management\n\n```bash\n# Interactive setup (recommended)\nai setup\n\n# Manual API key setup\nai config --set-openai-key sk-your-openai-key-here\nai config --set-anthropic-key sk-ant-your-anthropic-key-here\n\n# Check API key status\nai config --show-keys\n```\n\nAPI keys are stored securely in `~/.config/ai/config.json` and can also be set via environment variables:\n\n```bash\nexport OPENAI_API_KEY=sk-your-openai-key-here\nexport ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here\n```\n\n### Reset Configuration\n\n```bash\nai config --reset\n```\n\n### Export/Import Configuration\n\n```bash\n# Export configuration to a file\nai config --export my-config.json\n\n# Import configuration from a file\nai config --import my-config.json\n```\n\n### Export All Data\n\nExport all your AI agent data (configuration, API keys, conversation history) to a zip file:\n\n```bash\nai export\n```\n\nThis creates `~/ai-agent.zip` containing:\n- Configuration settings (model, temperature, etc.)\n- API keys (OpenAI, Anthropic)\n- All conversation history\n\nTo restore on another machine:\n```bash\n# Copy the zip file to the target machine, then:\nunzip ~/ai-agent.zip -d ~\n```\n\n## Configuration Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `model` | string | `gpt-3.5-turbo` | AI model to use |\n| `temperature` | number | `0.7` | Response creativity (0.0-2.0) |\n| `maxTokens` | number | `1000` | Maximum response length |\n| `systemPrompt` | string | `You are a helpful AI assistant.` | System prompt |\n| `verbose` | boolean | `false` | Enable verbose output |\n| `openaiApiKey` | string | `null` | OpenAI API key for GPT models |\n| `anthropicApiKey` | string | `null` | Anthropic API key for Claude models |\n| `apiEndpoint` | string | `null` | Custom API endpoint |\n\n## Command Line Options\n\n### Interactive Mode Options\n\n```bash\nai chat [options]\n```\n\nOptions:\n- `-m, --model \u003cmodel\u003e` - AI model to use\n- `-t, --temperature \u003ctemp\u003e` - Response creativity (0.0-2.0)\n- `--max-tokens \u003ctokens\u003e` - Maximum response length\n- `--system \u003cprompt\u003e` - System prompt to use\n- `--verbose` - Enable verbose output\n\n### Single Query Options\n\n```bash\nai ask \u003cquestion\u003e [options]\n```\n\nSame options as interactive mode.\n\n## Examples\n\n### Enhanced Agent Usage\n\n```javascript\nimport { EnhancedAIAgent } from '@profullstack/ai';\n\nconst agent = new EnhancedAIAgent({\n  model: 'gpt-3.5-turbo',\n  temperature: 0.7\n});\n\n// AI can now read files, write files, and execute commands\nconst response = await agent.query('Read my package.json and create a simple README for this project');\nconsole.log(response);\n```\n\n### How Enhanced Mode Works\n\nWhen you ask the AI to perform file or command operations, it uses special ACTION syntax:\n\n```bash\nai \u003e can you read my package.json file?\n\n🤖 I'll read the package.json file to check its contents.\nACTION:READ_FILE:package.json\n\n⚠️  Auto-allowing action: Read file: package.json\n\n✅ Action completed successfully\n**File read:** `package.json`\n**Size:** 1280 characters, 62 lines\n[file contents displayed]\n```\n\n**Available ACTION Types:**\n- `ACTION:READ_FILE:path` - Read a file\n- `ACTION:WRITE_FILE:path:CONTENT_START\\ncontent\\nCONTENT_END` - Write to a file\n- `ACTION:DELETE_FILE:path` - Delete a file\n- `ACTION:LIST_FILES:directory` - List files in a directory\n- `ACTION:EXEC_COMMAND:command` - Execute a system command\n- `ACTION:DIFF_FILE:path:diff_content` - Apply diff-based changes to a file\n\nThe AI automatically uses these actions when you ask for file operations, command execution, or project analysis.\n\n### Basic Agent Usage (Text-only)\n\n```javascript\nimport { AIAgent } from '@profullstack/ai';\n\nconst agent = new AIAgent({\n  model: 'gpt-3.5-turbo',\n  temperature: 0.7\n});\n\nconst response = await agent.query('Hello, world!');\nconsole.log(response);\n```\n\n### File Operations\n\n```javascript\nimport { readFile, writeFile, executeCommand } from '@profullstack/ai';\n\n// These functions include built-in permission prompts\nconst content = await readFile('./myfile.txt');\nawait writeFile('./output.txt', 'Hello, world!');\nconst result = await executeCommand('npm test');\n```\n\n### Configuration Management\n\n```javascript\nimport { getConfig, updateConfig, setOpenAIKey, getOpenAIKey } from '@profullstack/ai';\n\n// Get current configuration\nconst config = getConfig();\nconsole.log(config);\n\n// Update configuration\nupdateConfig('temperature', 0.8);\nupdateConfig('model', 'gpt-4');\n\n// Set API keys\nsetOpenAIKey('sk-your-openai-key-here');\nsetAnthropicKey('sk-ant-your-anthropic-key-here');\n\n// Get API keys\nconst openaiKey = getOpenAIKey(); // Checks env var first, then config file\nconst anthropicKey = getAnthropicKey();\n```\n\n### Conversation History\n\n```javascript\nimport { AIAgent } from '@profullstack/ai';\n\nconst agent = new AIAgent();\n\nawait agent.query('Hello!');\nawait agent.query('How are you?');\n\n// Get conversation stats\nconst stats = agent.getStats();\nconsole.log(stats);\n\n// Export history\nconst history = agent.exportHistory('markdown');\nconsole.log(history);\n\n// Clear history\nagent.clearHistory();\n```\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/profullstack/ai.git\ncd ai\npnpm install\n```\n\n### Run Examples\n\n```bash\npnpm run example\n```\n\n### Run CLI Locally\n\n```bash\npnpm run cli\n```\n\n### Testing\n\nThe project includes a comprehensive test suite covering all enhanced features:\n\n```bash\n# Run all tests\npnpm test\n\n# Run individual test suites\nnode tests/basic.test.js            # Basic functionality tests\nnode tests/enhanced.test.js         # Enhanced agent tests\nnode tests/enhanced-features.test.js # Comprehensive feature tests\n```\n\n**Test Coverage:**\n- **31 total tests** across 3 test suites\n- **100% pass rate** - All functionality working\n- **Enhanced features**: Action parsing, permission system, approved commands\n- **File operations**: Diff parsing, structure validation\n- **Configuration**: Load, update, reset operations\n- **Error handling**: Unknown actions, edge cases\n\nThe tests run without requiring API keys and validate all core functionality.\n\n## API Reference\n\n### EnhancedAIAgent Class\n\nThe enhanced agent extends AIAgent with file and command capabilities.\n\n#### Constructor\n\n```javascript\nnew EnhancedAIAgent(options)\n```\n\nOptions:\n- `model` - AI model to use\n- `temperature` - Response creativity\n- `maxTokens` - Maximum response length\n- `system` - System prompt\n- `verbose` - Enable verbose output\n- `enableActions` - Enable file/command operations (default: true)\n\n#### Methods\n\n- `query(message)` - Send a message and get a response (with action processing)\n- `clearHistory()` - Clear conversation history\n- `getHistory()` - Get conversation history\n- `getStats()` - Get conversation statistics\n- `exportHistory(format)` - Export history in specified format\n- `setActionsEnabled(enabled)` - Enable/disable action processing\n- `getActionsEnabled()` - Check if actions are enabled\n\n### AIAgent Class\n\nBasic text-only agent without file/command capabilities.\n\n#### Constructor\n\n```javascript\nnew AIAgent(options)\n```\n\nOptions:\n- `model` - AI model to use\n- `temperature` - Response creativity\n- `maxTokens` - Maximum response length\n- `system` - System prompt\n- `verbose` - Enable verbose output\n\n#### Methods\n\n- `query(message)` - Send a message and get a response\n- `clearHistory()` - Clear conversation history\n- `getHistory()` - Get conversation history\n- `getStats()` - Get conversation statistics\n- `exportHistory(format)` - Export history in specified format\n\n### Configuration Functions\n\n- `getConfig()` - Get current configuration\n- `updateConfig(key, value)` - Update configuration value\n- `resetConfig()` - Reset to default configuration\n- `exportConfig(filePath)` - Export configuration to file\n- `importConfig(filePath)` - Import configuration from file\n- `validateConfig(config)` - Validate configuration\n- `getAvailableModels()` - Get list of available models\n- `getConfigSchema()` - Get configuration schema\n### Action Functions\n\nFile and command operations with built-in permission prompts:\n\n- `readFile(filePath)` - Read a file with permission check\n- `writeFile(filePath, content)` - Write to a file with permission check\n- `deleteFile(filePath)` - Delete a file with permission check\n- `executeCommand(command, options)` - Execute a command with permission check\n- `listFiles(dirPath)` - List files in a directory\n- `fileExists(filePath)` - Check if a file exists\n\n### Permission Functions\n\n- `resetPermissions()` - Reset all action permissions\n- `showPermissions()` - Display current permission settings\n- `ACTION_TYPES` - Constants for action types\n- `PERMISSION_LEVELS` - Constants for permission levels\n\n### API Key Functions\n\n- `getOpenAIKey()` - Get OpenAI API key (env var or config file)\n- `setOpenAIKey(key)` - Set OpenAI API key in config file\n- `getAnthropicKey()` - Get Anthropic API key (env var or config file)\n- `setAnthropicKey(key)` - Set Anthropic API key in config file\n\n## License\n\nMIT\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Support\n\nFor support, please open an issue on GitHub or contact us at support@profullstack.com.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprofullstack%2Fai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprofullstack%2Fai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprofullstack%2Fai/lists"}