🚀 Hypz CLI - Autonomous Developer Agent

An autonomous developer agent that takes project requests and completes them fully with minimal interruptions. Hypz runs directly in your terminal on any OS (Linux, macOS, Windows) and can create entire projects, fix errors, and execute tasks independently.

📦 Installation

Quick Install (Recommended)

Using curl:

curl -fsSL https://raw.githubusercontent.com/ysr-hameed/hypz-cli/main/install.sh | bash

Using wget:

wget -qO- https://raw.githubusercontent.com/ysr-hameed/hypz-cli/main/install.sh | bash

NPM Install

npm install -g hypz-cli

Manual Install

git clone https://github.com/ysr-hameed/hypz-cli.git
cd hypz-cli
npm install
npm run build
npm link

Requirements

• Node.js v16 or higher
• npm or yarn

✨ Features

• 🤖 Fully Autonomous: Completes tasks with minimal user interaction
• 💬 Conversational Mode: Chat with the agent after task completion to add features or fix issues
• 🌐 Multi-LLM Support: Works with ChatGPT, Claude, Gemini, Grok, OpenRouter, or custom providers
• 📁 Complete Project Management: Creates, edits, renames, and deletes files and folders
• 🔧 Terminal Integration: Runs commands and detects/fixes errors automatically
• 💾 Persistent Context: Maintains memory of project state throughout task execution
• 🎨 Beautiful CLI UI: Clean, modern interface with keyboard navigation
• 🔒 Secure Configuration: API keys stored securely in local config
• 📊 Enhanced Logging: Detailed terminal output with line-by-line diffs, API timing, and real-time progress

🚀 Quick Start

1. Initialize Configuration

Run the setup command to configure your LLM provider:

hypz start

This will guide you through:

• Selecting an LLM provider (ChatGPT, Claude, Gemini, Grok, OpenRouter, or Custom)
• Choosing a model
• Entering your API key
• Validating the connection

2. Run a Task

Simply describe what you want to build:

hypz run "Create a REST API for managing student results"

Or run without arguments for interactive mode:

hypz run

3. View Configuration

Check your current configuration:

hypz config

🎯 Usage Examples

Create a Backend API

hypz run "Make a CRUD API for managing student results in a backend folder with Express and TypeScript"

Build a Frontend App

hypz run "Create a React Todo app with TypeScript, Tailwind CSS, and local storage"

Set Up a Full Stack Project

hypz run "Initialize a Next.js project with TypeScript, Prisma, and PostgreSQL integration"

Fix and Improve

hypz run "Add error handling and input validation to the existing API"

🔧 Supported LLM Providers

Latest AI Models

• ChatGPT (OpenAI): gpt-4-turbo, gpt-4o, gpt-4o-mini
• Claude (Anthropic): claude-3-5-sonnet-20241022, claude-3-opus, claude-3-sonnet
• Gemini (Google): gemini-2.0-flash-exp, gemini-1.5-pro, gemini-1.5-flash
• DeepSeek: deepseek-chat, deepseek-coder (optimized for coding)
• Grok (xAI): grok-beta, grok-2
• Mistral AI: mistral-large-latest, mistral-medium-latest
• OpenRouter: Access to multiple models through one API
• Custom Model: Use any OpenAI-compatible API

Getting API Keys

• OpenAI: https://platform.openai.com/api-keys
• Anthropic: https://console.anthropic.com/
• Google: https://makersuite.google.com/app/apikey
• DeepSeek: https://platform.deepseek.com/
• xAI: https://x.ai/
• Mistral: https://console.mistral.ai/
• OpenRouter: https://openrouter.ai/keys

💡 Advanced Features

Intelligent Error Recovery

Hypz automatically:

• Detects compilation and runtime errors
• Analyzes error messages and stack traces
• Fixes root causes, not just symptoms
• Verifies fixes work before continuing

Interactive Problem Solving

When you report an issue:

hypz run "I'm getting an error when running npm start"

Hypz will:

1. Ask for the exact error message
2. Analyze your codebase
3. Identify the root cause
4. Implement a fix
5. Verify it works

Detailed Terminal Output

Every action is logged in detail:

• API Call Tracking: See response times and which model is being called
• File Diffs: Line-by-line changes with ++ (added) and -- (removed) indicators
• Command Execution: Full output from every terminal command
• AI Reasoning: Understand why the AI makes specific decisions
• Real-time Progress: Live updates for each step

See ENHANCED_LOGGING.md for more details.

Smart Code Generation

• Generates complete, production-ready code
• No placeholders or "TODO" comments
• Includes error handling and edge cases
• Follows best practices and conventions
• Adds documentation and comments

🏗️ How It Works

1. Understanding: Hypz analyzes your request and breaks it into actionable steps
2. Planning: Generates a complete execution plan
3. Execution: Creates files, installs dependencies, runs commands
4. Error Detection: Automatically detects and fixes errors
5. Iteration: Continues working until the task is fully complete
6. Summary: Provides a comprehensive report of all changes

🎨 Project Structure

hypz-cli/
├── src/
│   ├── commands/           # CLI commands
│   │   ├── start.ts       # Setup flow
│   │   ├── run.ts         # Task execution
│   │   └── config.ts      # Configuration management
│   ├── llm/
│   │   └── client.ts      # LLM provider clients
│   ├── utils/
│   │   ├── config.ts      # Config storage
│   │   ├── filesystem.ts  # File operations
│   │   ├── terminal.ts    # Command execution
│   │   └── ui.ts          # UI components
│   ├── types/
│   │   └── index.ts       # TypeScript types
│   ├── cli.ts             # CLI entry point
│   └── index.ts           # Module exports
├── package.json
├── tsconfig.json
└── README.md

🔒 Security

• API keys are stored locally in ~/.hypz/config.json
• Keys are never logged or displayed in full
• Destructive operations require confirmation
• All data stays on your machine

🛠️ Development

Build from Source

# Clone the repository
git clone https://github.com/yourusername/hypz-cli.git
cd hypz-cli

# Install dependencies
npm install

# Build
npm run build

# Link for local development
npm link

# Run
hypz start

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Watch mode for development
• npm run lint - Run ESLint
• npm test - Run tests

📝 Configuration File

Configuration is stored at: ~/.hypz/config.json

Example structure:

{
    "llm": {
        "provider": "chatgpt",
        "model": "gpt-4-turbo-preview",
        "apiKey": "sk-..."
    },
    "lastUpdated": "2025-12-05T00:00:00.000Z"
}

🤝 Contributing

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

📄 License

MIT License - see LICENSE file for details

🐛 Troubleshooting

"No configuration found"

Run hypz start to set up your LLM provider.

API Connection Failed

• Verify your API key is correct
• Check your internet connection
• Ensure you have credits/quota remaining with your provider

Command Execution Errors

• Hypz will automatically attempt to fix most errors
• Check that required tools (npm, node, etc.) are installed
• Review the error output for specific issues

🌟 Features Coming Soon

• Project templates
• Git integration
• Multi-language support
• Team collaboration features
• Custom agent personalities
• Plugin system

💬 Support

For issues, questions, or suggestions, please open an issue on GitHub.

Made with ❤️ by the Hypz team